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
- numbered
- list
#. another numbered
#. list
- another numbered
- 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.
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.
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.
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
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 |
Links¶
http://microsoft.com
`Google <http://google.com>`_
This paragraph links to `the yahoo site`_.
.. _the yahoo site: http://yahoo.com/
This paragraph links to the yahoo site.
Table of contents¶
.. contents::
Contents
- Detailed reStructuredText and Sphinx example file
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.

Caption goes here.
Text after the image goes here.
To insert a figure with no caption, replace the caption with an empty comment (“..”):

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 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>
More information¶
intro to sphinx http://docs.writethedocs.org/tools/sphinx/
rst primer http://sphinx-doc.org/rest.html
first steps w sphinx http://sphinx-doc.org/tutorial.html
links http://sphinx-doc.org/markup/inline.html#ref-role
downloads http://sphinx-doc.org/markup/inline.html#referencing-downloadable-files
http://reinout.vanrees.org/weblog/2009/10/30/restructured-text-cheat-sheet.html
RST cheat sheet http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html