Detailed reStructuredText and Sphinx example file

Welcome! This Sphinx reference file shows reStructured Text (rst) code followed by its html output.

General formatting

Paragraphs that spread across
multiple lines in the source file
will display on one line in the
built html file.

The source file uses two line breaks
to indicate a paragraph break.

Paragraphs that spread across multiple lines in the source file will display on one line in the built html file.

The source file uses two line breaks to indicate a paragraph break.

a *italic* b **bold** c ``literal`` d

a italic b bold c literal d

a :emphasis:`emphasis` b :strong:`strong` c :literal:`literal`
d :subscript:`subscript` e :superscript:`superscript` f
:title-reference:`title-reference` g

a emphasis b strong c literal d subscript e superscript f title-reference g

character escaping with backslashes: thisis\ *one*\ word displays as thisisoneword

escaping backslashes: o\\o/o displays as o\o/o

Smart quotes, dashes, and Unicode

Sphinx automatically converts double dashes to unicode dashes, and quotes to smart quotes.

To add the registered trademark symbol ® or (R) with a space before and after the symbol, first insert this line at the bottom of the file:

.. |reg|    unicode:: U+000AE .. REGISTERED SIGN

Then in the text where you want the symbol to display, use |reg| like this:

abc--def |reg| ghi "jkl" 'mno'

abc–def ® ghi “jkl” ‘mno’

To show the symbol without a space before the symbol, which is the correct way to do it, use an “escaped space” by typing a backslash and then a space (word\ |reg|).

EXAMPLE: Anaconda®

To add the copyright symbol © or (C) with a space before and after the symbol, first insert this line at the bottom of the file:

.. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN

Then in the text where you want the symbol to display, use |copy| like this:

abc--def |copy| ghi "jkl" 'mno'

abc–def © ghi “jkl” ‘mno’

To show the symbol without a space before the symbol, use an escaped space by typing a backslash and then a space (Copyright\ |copy|).

EXAMPLE: Copyright© 2017, Anaconda, Inc.

If any further unicode symbols are needed, refer to this list: http://docutils.sourceforge.net/docutils/parsers/rst/include/xhtml1-lat1.txt

Lists and indentation

* bullet list
* with a very long second item
  on two lines.
  • bullet list
  • with a very long second item on two lines.
1. numbered
2. list
  1. numbered
  2. list
#. another numbered
#. list
  1. another numbered
  2. list
* bullet
* list

  * with
  * nesting

* which then continues
  • bullet
  • list
    • with
    • nesting
  • which then continues
This is a paragraph split across
two lines.

    This is an indented paragraph below it. On the docs site these display with
    big blue quote marks, so we usually avoid them.

Here is another left justified paragraph.

| This paragraph with line blocks
| has line breaks in the html output
| just as it does in the rst input.

.. This is a comment.

..
    This whole indented block
    is a comment.

    Still in the comment.

Now out of the comment.

This is a paragraph split across two lines.

This is an indented paragraph below it. On the docs site these display with big blue quote marks, so we usually avoid them.

Here is another left justified paragraph.

This paragraph with line blocks
has line breaks in the html output
just as it does in the rst input.

Now out of the comment.

More complex lists and indentation

This example shows more complex indentation for nested lists and embedded code blocks.

Sphinx likes sub-items under a list item to be even with the first text in the item. So an item in an unordered (bullet) list might begin with “* One”, and a sub-item under that would begin with two spaces, while an item in an ordered (numbered) list might begin with “1. One” or “#. One”, and a sub-item under that would begin with three spaces.

Command blocks after a double colon should be indented four spaces past the start of the text in the line above.

#. Item 1.

#. Item 2.

   More text.

   #. Part A::

          command block

      OR::

          alternate command block

   #. Part B.

#. Item 3. This item can have a long paragraph across multiple lines. One two
   three four five six seven eight nine ten eleven twelve thirteen fourteen
   fifteen sixteen seventeen eighteen nineteen twenty.

   - Option A::

         command block

   - Option B::

         alternate command block

   NOTE: Further information can go here. One two three four five six seven
   eight nine ten.

#. Item 4.

  1. Item 1.

  2. Item 2.

    More text.

    1. Part A:

      command block

      OR:

      alternate command block

    2. Part B.

  3. Item 3. This item can have a long paragraph across multiple lines. One two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen twenty.

    • Option A:

      command block

    • Option B:

      alternate command block

    NOTE: Further information can go here. One two three four five six seven eight nine ten.

  4. Item 4.

Code blocks

rst

Next we’ll show how we’re displaying these blocks of rst code:

.. code-block:: rst

    This is a paragraph split across
    two lines.

This is a paragraph split across
two lines.

HTML

.. code-block:: html

    <html>
        <head>Hello!</head>
        <body>Hello, world!</body>
    </html>

<html>
    <head>Hello!</head>
    <body>Hello, world!</body>
</html>

YAML

.. code-block:: yaml

    envs_dirs:
      - ~/my-envs
      - /opt/anaconda/envs

envs_dirs:
  - ~/my-envs
  - /opt/anaconda/envs

bash

.. code-block:: bash

    ls
    pwd
    touch a.txt

ls
pwd
touch a.txt

python

.. code-block:: python

    for i in range(10):
        print(i)

for i in range(10):
    print(i)

none

If no other type applies, use “none”. It can be useful for obscure languages or mixtures of languages like this mix of bash and python.

.. code-block:: none

    cat program.py

    for i in range(10):
        print(i)

cat program.py

for i in range(10):
    print(i)

Captions

Now in Sphinx 1.3, captions can be added to code blocks as well:

.. code-block:: python
    :caption: this.py
    :name: this-py

    print('Explicit is better than implicit.')
this.py
print('Explicit is better than implicit.')

Tables

Grid table with header:

+----------+-----------+-------+
| a        | b         | c     |
+==========+===========+=======+
| north    | north     | north |
| west     |           | east  |
+----------+-----------+-------+
| west     | center    | east  |
+----------+-----------+-------+
| south    | south     | south |
|          |           |       |
| west     |           | east  |
+----------+-----------+-------+
a b c
north west north north east
west center east

south

west

 south

south

east

Note that line breaks in the south west and south east boxes are preserved and line breaks in the north west and north east boxes are not.

Grid table without header:

+----------+-----------+-------+
| north    | north     | north |
| west     |           | east  |
+----------+-----------+-------+
| west     | center    | east  |
+----------+-----------+-------+
| south    | south     | south |
| west     |           | east  |
+----------+-----------+-------+
north west north north east
west center east
south west south south east

“Simple tables” are easier to write, but must have more than one row, and the first column cannot contain multiple lines:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
A B A and B
False False False
True False False
False True False
True True True

Table of contents

.. contents::

Adding the :local: option removes the page title “Detailed reStructuredText and Sphinx example file” and the table of contents title “Contents”. You can see how it displays at the top of this file.

.. contents::
    :local:

Another file might use this table of contents:

.. contents:: Table of Contents
    :depth: 2

The title “Table of Contents” overrides the default title “Contents”. The depth option specifies that only the two top levels of headers should be displayed in the table of contents.

Index files

Instead of using the contents directive to show a table of its own contents, the index file uses the toctree directive to show a table of other files. All files in the archive should be reachable from the toctrees in the index. Files can also contain toctrees of their own, which can lead to other files not referenced directly by the index. Toctrees may be hidden, in which case they will be used to build the left navigation column but not appear in the main page text.

.. toctree::
    :maxdepth: 2

    file-one
    file-two
    file-three

Images

Images can use either the “image” directive or the “figure” directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#images

The “figure” directive supports captions, legends, numbering, and a figure class assignment, and is preferred to the “image” directive.

Remote linking an image like this is allowed in rst in general, but produces a ‘nonlocal image’ warning in Sphinx:

.. image:: http://upload.wikimedia.org/wikipedia/commons/thumb/9/9e/Green_eyes_kitten.jpg/120px-Green_eyes_kitten.jpg

Warnings in a local build will cause Travis CI to fail. So, make sure your images are local images. It might also be possible to embed a nonlocal image similarly to embedding a YouTube video, as explained below, but embedding nonlocal images is probably best avoided anyway. Here’s a local image.

To be sure there is enough space between an image and the text after it, insert a “pipe” or “vertical bar” character (“|”) after each image. These may also be inserted anywhere else to add extra space.

.. figure:: /img/rst-cheatsheet-earth.jpg

   Caption goes here.

|

Text after the image goes here.

To insert a figure with no caption, replace the caption with an empty comment (".."):

.. figure:: /img/rst-cheatsheet-earth.jpg

   ..

|

Text after the image goes here.
../../_images/rst-cheatsheet-earth.jpg

Caption goes here.


Text after the image goes here.

To insert a figure with no caption, replace the caption with an empty comment (“..”):

../../_images/rst-cheatsheet-earth.jpg

Text after the image goes here.

To insert an inline image:

Click the download button |download| to download the file.

.. |download| image:: /img/download.png
              :width: 10 px

Click the download button download to download the file.

The “width” line is optional.

When using a full-size screenshot, constrain the width to 50% so it does not appear oversized:

.. figure:: /img/filename.png
   :width: 50%

   ..

|

Downloadable files

Downloadable files can be anywhere in the directory structure. It’s usually easiest to keep them in the same directory as the .rst file that refers to them.

See :download:`this example script <../example.py>`.

If there are multiple downloadable files with the same name, Sphinx will rename them and the links to them in the html. For example, if a graphics project has two different files named points/example.py and lines/example.py and a math project has one file named example.py, the _downloads directory will have files named example.py, example1.py, and example2.py. If you wish to prevent this, check the directory for these renamed files, and change the filenames so they do not overlap. In this case the files could be changed to graphics-example-points.py, graphics-example-lines.py, and math-example.py.

Notes

.. note:: This is a note admonition.
    This is the second line of the first paragraph.

    - The note contains all indented body elements
      following.
    - It includes this bullet list.

Note

This is a note admonition. This is the second line of the first paragraph.

  • The note contains all indented body elements following.
  • It includes this bullet list.

YouTube videos (and other raw html in rst files)

On YouTube you can click “share” and then “embed”, and it will show iframe code like this.

.. raw:: html

    <iframe width="560" height="315" src="https://www.youtube.com/embed/UaIvrDWrIWM" frameborder="0" allowfullscreen></iframe>