mount yard documentation at /docs

yard-mount.rb

# 1) Running a raw RackAdapter in config.ru mounted at '/' works fine
require 'bundler/setup'
require 'yard'

run YARD::Server::RackAdapter.new(
  {'surfiki' => [YARD::Server::LibraryVersion.new('surfiki', nil, File.expand_path('../.yardoc', __FILE__))]},
  {
    :single_library => true,
    :caching        => false
  })

# 2) Mapping the adapter to a path fails because
#    the request path will be anchored at '/yard'
map '/yard' do
  # This will return 404, X-CASCADE: pass and go downstream
  run YARD::Server::RackAdapter.new(
    {'surfiki' => [YARD::Server::LibraryVersion.new('surfiki', nil, File.expand_path('../.yardoc', __FILE__))]},
    {
      :single_library => true,
      :caching        => false
    })
end

run Surfiki::Application  # downstream rails app

# 3) Using Rail's `mount` helper in routes.rb will serve up the proper html,
#    but the generated docs will reference top level assets like
#    /js/live.js and /css/custom.css. Is there a way to prefix
#    all the generated docs with '/doc'?
# config/routes.rb

doc_server = YARD::Server::RackAdapter.new(
  {'surfiki' => [YARD::Server::LibraryVersion.new('surfiki', nil, File.expand_path('../../.yardoc', __FILE__))]},
  {
    :single_library => true,
    :caching        => false
  })

Surfiki::Application.routes.draw do
  mount docs => '/doc', anchor: false

  # snip...
end

# 4) Proposed changes for mounting docs alongside another rack app. This
#    change would be more for convenience and would be backwards compatible
#    with the old interface. Additionally, change the default routing behavior
#    to not anchor paths, but allow an option `:anchor` for configuration

# General rack application. If there's a .yardoc directory in the same
# directory as .config.ru, then default the lib name to the directory name,
# and default options to `{single_library: true, caching: false}`
use YARD::Server::RackMiddleware
run YourApp

# or... also gives defaults if .yardoc is detected
run YARD::Server::RackAdapter

Alternatively, there's a project called guard-yard which I've found useful for a similar situation.