Thib’s ReadTheDocs Test Project

Essential Inline Markup

Italic

Preferred: *...*

Synonyms: :emphasis:`...`

Source:

This is normal. *This is italic.* This is normal again.

Result:

This is normal. This is italic. This is normal again.

References:

Bold

Preferred: **...**

Synonyms: :strong:`...`

Source:

This is normal. **This is bold.** This is normal again.

Result:

This is normal. This is bold. This is normal again.

References:

Literal

Preferred: ``...``

Synonyms: :literal:`...`

Source:

This is normal. ``This is literal.`` This is normal again.

Result:

This is normal. This is literal. This is normal again.

Other Inline Markup

Interstitial Heading

A rubric is rendered as an interstitial heading but does not become part of the structural hierarchy of the document. Useful for marking the footnotes section at the end of a page.

Source:

This is a paragraph.

.. rubric:: This is a rubric

This is another paragraph.

Result:

This is a paragraph.

This is a rubric

This is another paragraph.

References:

Superscript

Preferred: :sup:`...`

Synonyms: :superscript:`...`

Source:

Plot the parabola y = x :sup:`2` + 1.

Result:

Plot the parabola y = x 2 + 1.

References:

Subscript

Preferred: :sub:`...`

Synonyms: :subscript:`...`

Source:

Water is H :sub:`2` O.

Result:

Water is H 2 O.

References:

Title Reference

Used for the title of a book, periodical, etc.

Preferred: :title-reference:`...`

Synonyms: :title:`...`, :t:`...`

Source:

:title-reference:`Design Patterns` is a great book.

Result:

Design Patterns is a great book.

References:

Semantic Markup

Note

These roles are part of Sphinx.

Sphinx defines a number of roles for semantic markup.

:abbr:`AAA (expansion of AAA)`

Abbreviation and expansion.

:abbr:`FTP (File Transfer Protocol)` -> FTP

:command:`...`

OS-level command.

:command:`rm` -> rm

:dfn:`...`

Defining instance of a term.

:dfn:`LOCKSS` -> LOCKSS

:file:`...`

File or directory name.

Within the contents, you can use curly braces to indicate a variable part

:file:`/usr/lib/python2.{x}/site-packages` -> /usr/lib/python2.x/site-packages

:guilabel:`...`

UI labels (button text, field name…)

Within the contents, an accelerator key can be marked specially by preceding it with an ampersand (two ampersands result in a literal ampersand).

:guilabel:`&Cancel` -> Cancel

:kbd:`...`

Sequence of keystrokes.

:kbd:`Control + Alt + Delete` -> Control + Alt + Delete

:mailheader:`...`

Mail or HTTP header.

:mailheader:`Content-Type` -> Content-Type

:manpage:`COMMAND(N)`

Unix man page and section

:manpage:`ls(1)` -> ls(1)

:menuselection:

A menu selection sequence, separated by -->.

Supports ampersand accelerators like :guilabel:.

:menuselection:`Edit --> Copy` -> Edit ‣ Copy

:mimetype:

Media type, or major or minor portion of a media type.

:mimetype:`text/html` -> text/html

:program:

Executable program.

:program:`configure.sh` -> configure.sh

:regexp:

Regular expression.

:regexp:`^ab*c$` -> ^ab*c$

:samp:

Piece of sample text.

Within the contents, you can use curly braces to indicate a variable part, as in :file:. Curly braces are escaped with a backslash.

:samp:`print {variable} + 1` -> :samp:`print {variable} + 1`

Notes:

  • :guilabel: seems to have bugs. In HTML output, the accelerator key surrounds the affected character with a distinguishable <span> but seemingly not resulting in a different visual. In PDF output, the double ampersand remains without being escaped to a single ampersand.

References:

Lists

Bullet List

Source:

*  This is the first bullet list item.  The blank line above the
   first list item is required; blank lines between list items
   (such as below this paragraph) are optional.

*  This is the first paragraph in the second item in the list.

   This is the second paragraph in the second item in the list.
   The blank line above this paragraph is required.  The left edge
   of this paragraph lines up with the paragraph above, both
   indented relative to the bullet.

   *  This is a sublist.  The bullet lines up with the left edge of
      the text blocks above.  A sublist is a new list so requires a
      blank line above and below.

*  This is the third item of the main list.

This paragraph is not part of the list.

Result:

  • This is the first bullet list item. The blank line above the first list item is required; blank lines between list items (such as below this paragraph) are optional.

  • This is the first paragraph in the second item in the list.

    This is the second paragraph in the second item in the list. The blank line above this paragraph is required. The left edge of this paragraph lines up with the paragraph above, both indented relative to the bullet.

    • This is a sublist. The bullet lines up with the left edge of the text blocks above. A sublist is a new list so requires a blank line above and below.

  • This is the third item of the main list.

This paragraph is not part of the list.

Notes:

  • Bullet marker can be *, - or +.

References:

Enumerated List

Source:

1. Item 1

2. Item 2

   1. Item 2.1

   2. Item 2.2

3. Item 3

Result:

  1. Item 1
  2. Item 2
    1. Item 2.1
    2. Item 2.2
  3. Item 3

Notes:

  • Supported enumerators are 1, 2, 3..., A, B, C..., a, b, c..., I, II, III..., i, ii, iii...
  • Supported markers are followed by a dot (e.g. 1.), followed by a parenthesis (e.g. 1)), or surrounded by parentheses (e.g. (1)).

References:

Definition List

Source:

term 1
    Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

Result:

term 1
Definition 1.
term 2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

Notes:

  • Terms can also have qualifiers but the rendering does not seem to work with the version of Sphinx and Sphinx_rtd_theme we are using.

References:

Asides

Admonitions

Admonitions are side notes offset from the main body of text by a box. Examples include “Warning”, “Note” and “Important”. The specific admonition directives attention, caution, danger, error, hint, important, note, tip, and warning are implemented in terms of the generic admonition directive.

PDF Output

In local PDF output, all specific admonitions are rendered in a boxed area, but the generic admonition is rendered slightly differently with a horizontal line above and below.

Admonition

Source:

.. admonition:: Check This Out!

   This is a generic Admonition. It has the custom title "Check This Out!"

   It can have multiple paragraphs.

Result:

Check This Out!

This is a generic Admonition. It has the custom title “Check This Out!”

It can have multiple paragraphs.

Attention

Source:

.. attention::

   This is an Attention admonition.

   It can have multiple paragraphs.

Result:

Attention

This is an Attention admonition.

It can have multiple paragraphs.

Caution

Source:

.. caution::

   This is a Caution admonition.

   It can have multiple paragraphs.

Result:

Caution

This is a Caution admonition.

It can have multiple paragraphs.

Danger

Source:

.. danger::

   This is a Danger admonition.

   It can have multiple paragraphs.

Result:

Danger

This is a Danger admonition.

It can have multiple paragraphs.

Error

Source:

.. error::

   This is an Error admonition.

   It can have multiple paragraphs.

Result:

Error

This is an Error admonition.

It can have multiple paragraphs.

Hint

Source:

.. hint::

   This is a Hint admonition.

   It can have multiple paragraphs.

Result:

Hint

This is a Hint admonition.

It can have multiple paragraphs.

Important

Source:

.. important::

   This is an Important admonition.

   It can have multiple paragraphs.

Result:

Important

This is an Important admonition.

It can have multiple paragraphs.

Note

Source:

.. note::

   This is a Note admonition.

   It can have multiple paragraphs.

Result:

Note

This is a Note admonition.

It can have multiple paragraphs.

Tip

Source:

.. tip::

   This is a Tip admonition.

   It can have multiple paragraphs.

Result:

Tip

This is a Tip admonition.

It can have multiple paragraphs.

Warning

Source:

.. warning::

   This is a Warning admonition.

   It can have multiple paragraphs.

Result:

Warning

This is a Warning admonition.

It can have multiple paragraphs.

Topic

Source:

.. topic:: Topic Title

   Subsequent indented lines comprise
   the body of the topic, and are
   interpreted as body elements.

Result:

Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

Notes:

Result:

  • In HTML: not rendered all that specially.
  • In PDF: rendered as a full-width box.

References:

Verbatim

Code

Tip

This directive is part of basic reStructuredText, but has fewer features than its Sphinx counterparts code-block and literalinclude, which are recommended instead.

References:

Source:

.. code:: java

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

public static void main(String[] args) {
  System.out.println("Hello world!");
}

Source:

.. code:: java
   :number-lines:

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

1 public static void main(String[] args) {
2   System.out.println("Hello world!");
3 }

Source:

.. code:: java
   :number-lines: 123

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

123 public static void main(String[] args) {
124   System.out.println("Hello world!");
125 }

Notes:

  • The language keywords accepted are those accepted by Pygments.

References:

Code Block

Note

This directive is part of Sphinx.

PDF Output

In HTML output, code and code-block look the same, but in PDF output, code-block is rendered inside a boxed area, with small, a2ps-style line numbers outside the boxed area.

Source:

.. code-block:: java

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

public static void main(String[] args) {
  System.out.println("Hello world!");
}

Source:

.. code-block:: java
   :linenos:

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

1
2
3
public static void main(String[] args) {
  System.out.println("Hello world!");
}

Source:

.. code-block:: java
   :lineno-start: 123

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

123
124
125
public static void main(String[] args) {
  System.out.println("Hello world!");
}

Source:

.. code-block:: java
   :emphasize-lines: 2,3

   public static void main(String[] args) {
     // These two lines are highlighted
     System.out.println("Hello world!");
   }

Result:

public static void main(String[] args) {
  // These two lines are highlighted
  System.out.println("Hello world!");
}

Source:

.. code-block:: java
   :caption: Title of the code block

   public static void main(String[] args) {
     System.out.println("Hello world!");
   }

Result:

Title of the code block
public static void main(String[] args) {
  System.out.println("Hello world!");
}

Source:

.. code-block:: java
   :dedent: 8

               These lines have source with 11 leading spaces:
               3 to align with the ``c`` of ``.. code-block``
               (by convention) and 12 proper ones. But the
               result is rendered with only 4 leading spaces,
               after being "de-indented" by 8.

Result:

    These lines have source with 11 leading spaces:
    3 to align with the ``c`` of ``.. code-block``
    (by convention) and 12 proper ones. But the
    result is rendered with only 4 leading spaces,
    after being "de-indented" by 8.

References:

Literal Include

Note

This directive is part of Sphinx.

The literalinclude directive is similar to code-block but takes its source from an external file. It has the same basic options, except that code-block’s direct argument is a Pygments language code whereas literalinclude’s is a file path, meaning the Pygments language keyword is specified with the :language: option instead.

It also accepts these additional options:

  • :encoding:: a file encoding like latin-1.
  • :lines:: the comma-separated list of line numbers (e.g. 3) or line number ranges either closed (e.g. 23-45) or open (e.g. -77 or 99-) controls which lines from the external file are actually included.
  • :start-after: and :end-before:: these independent options can be used to include only lines of the external file strictly after or strictly before (respectively) the first line containing the string given as an argument.
  • :start-at: and :end-at:: similar to :start-after: and :end-before:, but also includes the matched line in the output.
  • :prepend: and :append:: prepend or append (respectively) the line given as argument to the output.
  • :diff:: this option accepts another file path as argument and displays the unified diff from the :diff: argument file to the literalinclude argument file.

References:

Images

Image

The image directive accepts the optional parameters :alt:, :height:, :width:, :scale:, :align: and :target: (see definition).

Source:

.. image:: /images/test-image.png
   :alt: HTML alt text
   :width: 100px

Result:

HTML alt text

References:

Figure

The figure directive accepts an image file path as its direct argument; the first paragraph of its body is rendered as the caption and the remainder of its body as the “legend” (arbitrary body elements). It supports the same options as the image directive, plus :figwidth:.

Source:

.. figure:: /images/test-image.png
   :alt: HTML alt text

   This is the caption.

   This is the legend, paragraph 1.

   This is the legend, paragraph 2.

Result:

HTML alt text

This is the caption.

This is the legend, paragraph 1.

This is the legend, paragraph 2.

In HTML, the rendering is above.

In PDF, the rendering is on a page of its own.

References: