Infer title and heading from comment #223
Conversation
p8
force-pushed
the
features/default-titles
branch
2 times, most recently
from
2293c87 to
dce7139
Compare
|
I'm not sure if we should humanize the classname. For some modules and error classes I actually prefer the module name: https://deploy-preview-223--sdoc.netlify.app/classes/activejob/deserializationerror |
|
As an alternative, why don't we just put the module name as an For example, if I'm searching for "Active Record Associations", should I land on the API page that probably has more detail than necessary? Or should I end up on a guide that can gradually introduce me to the concept and link to API parts to dig deeper? |
|
@zzak the current PR doesn't humanize the titles, so this is conform your proposal. |
Some classes in Rails have a h1 heading defined in the RDoc comment. For example: https://github.com/rails/rails/blob/4e1fe73028f4b01c8e5179989511b21925f70b20/activesupport/lib/active_support/current_attributes.rb#L8 https://github.com/rails/rails/blob/4e1fe73028f4b01c8e5179989511b21925f70b20/actionpack/lib/action_controller/metal/strong_parameters.rb#L1159 This makes the heading more readable especially when there are a lot of namespaces. For SEO it helps if all classes have a h1 heading, but having to add them by hand is cumbersome when we can generate them instead. By looking at the comment of the class/module we can see if it has a `h1` heading when it's starting with `= ` or `# `. If the heading is missing we can generate a heading with the full name of the class instead. This will prevent us from having to add the h1 for each class in Rails. This also adds the `@options.title` to the `title` tag of every class.
p8
force-pushed
the
features/default-titles
branch
from
dce7139 to
60e05b5
Compare
In rails#223, we began generating default `<h1>` headings for modules. However, these headings were only generated for modules that had a description. If a module had no comment to begin with, it would not get a generated heading. Furthermore, since rails#280, each module's full name has been prominently displayed at the top of its page. These names are visually redundant with generated headings, which also use the full name. To unify the design and ensure that all modules have an `<h1>`, this commit converts each module's full name into an `<h1>` heading inside an `<hgroup>`, and uses postprocessing to pull any comment-based `<h1>` into the `<hgroup>`. This commit also renames the "Included Modules" section to "Inherits From", and moves any listed base class from the top of the page to the top of that section. This change focuses the `<h1>`, both visually and from an SEO perspective.
Some classes in Rails have a h1 heading defined in the RDoc comment.
For example:
https://github.com/rails/rails/blob/4e1fe73028f4b01c8e5179989511b21925f70b20/activesupport/lib/active_support/current_attributes.rb#L8
https://github.com/rails/rails/blob/4e1fe73028f4b01c8e5179989511b21925f70b20/actionpack/lib/action_controller/metal/strong_parameters.rb#L1159
This makes the heading more readable especially when there are a lot of
namespaces.
For SEO it helps if all classes have a h1 heading, but having to add
them by hand is cumbersome when we can generate them instead.
By looking at the comment of the class/module we can see if it has a
h1heading when it's starting with=or#. If the heading ismissing we can generate a heading with the full name of the class
instead. This will prevent us from having to add the h1 for each class
in Rails.
This change is backwards compatible and works without having to make changes in Rails.
This also adds the
@options.title("Ruby on Rails API") to thetitletag of every class, which also helps with SEO.I looked at the
:title:directive, but that only works if it hasn't been set yet and can'be overridden:https://github.com/ruby/rdoc/blob/cc40a39714d894180713032ac6049e192e72f3db/lib/rdoc/options.rb#L512-L518