This is a condensed version of this page: https://docs.ruby-lang.org/en/2.1.0/RDoc/Markup.html
=== Headers
outputs: <h3 id="label-Headers">Headers</h3>
= Headers
outputs: <h1 id="label-Headers">Headers</h1>
##
# This method does fun things
#
# = Example
#
# Example of fun things goes here ...
def do_fun_things
end
outputs: <h1 id="method-i-do_fun_things-label-Example">Example</h3>
---
outputs: <hr>
*, -, <digit>, or <letter> starts a list.
* this is a list with three paragraphs in
the first item. This is the first paragraph.
And this is the second paragraph.
1. This is an indented, numbered list.
2. This is the second item in that list
This is the third conventional paragraph in the
first list item.
* This is the second item in the original list
[cat] a small furry mammal
that seems to sleep a lot
[ant] a little insect that is known
to enjoy picnics
outputs:
<dl class="rdoc-list label-list">
<dt>cat</dt>
<dd>
<p>a small furry mammal that seems to sleep a lot</p>
</dd>
<dt>ant</dt>
<dd>
<p>a little insect that is known to enjoy picnics</p>
</dd>
</dl>
If you want the list bodies to line up to the left of the labels, use two colons:
cat:: a small furry mammal
that seems to sleep a lot
ant:: a little insect that is known
to enjoy picnics
If you want to introduce a verbatim section right after a list, it has to be less indented than the list item bodies, but more indented than the list label, letter, digit or bullet. For instance:
* point 1
* point 2, first paragraph
point 2, second paragraph
verbatim text inside point 2
point 2, third paragraph
verbatim text outside of the list (the list is therefore closed)
regular paragraph after the list
*word*
displays word in a bold font
_word_
displays word in an emphasized font
+word+
displays word in a code font
<b>text</b>
displays text in a bold font
<em>text</em>
displays text in an emphasized font (alternate tag: <i>)
<tt>text</tt>
displays text in a code font (alternate tag: <code>)
Links to starting with http:, https:, mailto:, ftp: or www. are recognized.
This is a link:
https://github.com/rdoc/rdoc
This resolves to an inline image:
https://www.ruby-lang.org/images/header-ruby-logo@2x.png
Classes and methods will be automatically linked to their definition.
This will be auto linked:
ActiveRecord
By default methods will only be automatically linked if they contain an _ (all methods can be automatically linked through the --hyperlink-all command line option).
This method gets auto-linked:
add_all
This method will not be auto-linked:
add
Use a # for single-word instance methods or :: for class methods:
#add
::add
Link to a section in the documentation with the class or method and then @heading-name:
RDoc::Markup@Links
These are all valid:
https://github.com/rdoc/rdoc
mailto:user@example.com
{RDoc Documentation}[http://rdoc.rubyforge.org]
{RDoc Markup}[rdoc-ref:RDoc::Markup]
These are the most common use cases for links. If you need something weird, here's the docs: RDoc::Markup@Links
:nodoc: / :nodoc: all
This directive prevents documentation for the element from being generated. For classes and modules, methods, aliases, constants, and attributes directly within the affected class or module also will be omitted. By default, though, modules and classes within that class or module will be documented. This is turned off by adding the all modifier.
module MyModule # :nodoc:
class Input
end
end
module OtherModule # :nodoc: all
class Output
end
end
In the above code, only class MyModule::Input will be documented.
:stopdoc: / :startdoc:
Stop and start adding new documentation elements to the current container. For example, if a class has a number of constants that you don't want to document, put a :stopdoc: before the first, and a :startdoc: after the last. If you don't specify a :startdoc: by the end of the container, disables documentation for the rest of the current file.