Is it possible to generate a single page per method?

[mullermp]

Hello Loren. We (AWS Ruby SDK) are needing to address some accessibility concerns with our docs. Our Client docs (i.e. s3) have many methods. We are investigating whether it's possible to have each method on a single page, and have it breadcrumbed under the Client's CodeObject. If this is possible, what is the best way to achieve this?

Also - we've had to make some minor changes to colors, link underlining, setting page language "en", etc. I am also wondering if any of these changes can be merged upstream or if any of them are considered breaking? https://github.com/aws/aws-sdk-ruby/pull/2861/files

Thanks

[lsegal]

We are investigating whether it's possible to have each method on a single page, and have it breadcrumbed under the Client's CodeObject. If this is possible, what is the best way to achieve this?

It's certainly possible to generate pages per method. YARD server already exposes individual method pages via permalink (example) and it should in fact be fully supported by the defaulte template already (breadcrumbs and all). The biggest limitation is that the yardoc CLI tool specifically omits method when generating:

https://github.com/lsegal/yard/blob/main/lib/yard/cli/yardoc.rb#L325-L358

The good news is this is very possible to customize by either having your plugin/extension manually generate said method objects (using the same methodology as #run_generate above), or by overriding the related YARD::CLI::Yardoc#all_objects to include said objects. Yes, that latter method is deprecated, but the reality is that message is probably a little outdated-- it was deprecated for other reasons (a lack of a @private tag), not because it's actually going anywhere. YARD doesn't have a track record of removing deprecated methods (and again, it probably no longer needs to be deprecated).

Hope that helps.

[lsegal]

I am also wondering if any of these changes can be merged upstream or if any of them are considered breaking?

As far as language settings go, this might be a little tougher. YARD doesn't make any assumptions about the code's language format, and arguably it would be incorrect to assume lang="en".

Link underlining etc would be acceptable as a PR (please include screenshots of what is being changed) but a change to lang etc would probably require some general purpose way to customize the language (without requiring code) if we were to default to English.

[mullermp]

As far as language settings go, this might be a little tougher. YARD doesn't make any assumptions about the code's language format, and arguably it would be incorrect to assume lang="en".

Yep, I figured as much. I think it would make sense for a language method in setup.rb that defaults to nil, and when overridden, will set lang=whatever when the language is set.

It's certainly possible to generate pages per method.

I will investigate and get back to this!

Link underlining etc

The color changing I think is straight forward. The link underlining, TBH, is ugly (see current S3 docs, it's every link pretty much), but I think some exceptions can be made to ignore summary signatures and some other areas.

[mullermp]

I wasn't able to get method to generate when overwriting all_objects. I may have to dig into internals. Any other advice? I created a rake task similar to the yardoc executable with a monkey patch like so:

task 'docs' do
  # We do all this work just to find the proper load path
  path = __FILE__
  while File.symlink?(path)
    path = File.expand_path(File.readlink(path), File.dirname(path))
  end
  $LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))

  require 'yard'
  module YARD
    module CLI
      class Yardoc
        def all_objects
          Registry.all(:root, :module, :class, :method)
        end
      end
    end
  end

  YARD::CLI::Yardoc.run(*ARGV)
end

Edit - I see the files are there, however, with no breadcrumb and styling!