kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Add explanation for GH links vs RDoc generated links cc #28608

Browse source
This commit is contained in:
Zachary Scott 2021-05-13 09:28:46 +09:00
parent 13327e0bec
commit 164545de36
1 changed files with 11 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
guides/source/api_documentation_guidelines.md
View file

@ -30,6 +30,17 @@ Please consult the RDoc documentation for help with the
and also take into account these [additional
directives](https://ruby.github.io/rdoc/RDoc/Parser/Ruby.html).
Links
-----
Rails API documentation are not meant to be viewed on GitHub and so links should use the RDoc [`link`](https://ruby.github.io/rdoc/RDoc/Markup.html#class-RDoc::Markup-label-Links) markup relative to the current API.
This is due to differences between GitHub Markdown and the generated RDoc that is published at [api.rubyonrails.org](https://api.rubyonrails.org) and [edgeapi.rubyonrails.org](https://edgeapi.rubyonrails.org).
For example, we use `[link:classes/ActiveRecord/Base.html]` to create a link to the `ActiveRecord::Base` class generated by RDoc.
This is preferred over absolute URLs such as `[https://api.rubyonrails.org/classes/ActiveRecord/Base.html]`, which would take the reader outside their current documentation version (e.g. edgeapi.rubyonrails.org).
Wording
-------