reStructuredText cheat sheet#

This cheat sheet explains how to use common reStructuredText formatting with the Sphinx documentation generator.

Headings#

Start each section in a page with a heading. Use H1 for the page’s title, H2 for the page’s sections and H3 for the subsections.

==========
Header One
==========

Header Two
==========

Header Three
------------

Header Four
^^^^^^^^^^^

Header Five
"""""""""""

Note

The lines below and above a header must match the length of the text.

H4 and H5 are discouraged and rarely used. Try to bring the headings up a level (for instance, create a new topic to house an H2 and its subsections so that the H2 is now an H1, and so forth); if you can’t, use bolding instead of H4s.

Tables of contents#

Structure#

Each index file uses the .. toctree:: directive to organize pages in a tree data structure, which is used to build a nested list of links to each page in the left navigation.

.. toctree::
    :maxdepth: 2

    file-one
    file-two
    file-three
    file-with-its-own-child-topics/index
    external link <https://www.google.com/>

By default, the .. toctree:: directive creates both left navigation and in-page navigation links to the child pages. Adding the :hidden: option to the directive creates left navigation only.

Orphan topics#

Sphinx requires that the toctree lists include all pages. If a page is not in any toctree list, it is a page with no parent page, or an “orphan” page, and the Sphinx build will produce an error. If for some reason a page must be in the documentation but not in the left navigation, the :orphan: directive can be added at the top of that page so that Sphinx will build without errors (as seen on this page!). Please avoid the :orphan: directive as much as possible.

Font formatting#

Code:

Use *italics* to emphasize information. Use sparingly.

Use **bolding** for UI elements, dropdown menus, and text contained in a cell.

Alternatively, use :emphasis:`emphasis` and :strong:`strong`.

And a few others, just in case: :subscript:`subscript`, :superscript:`superscript`, :title-reference:`title-reference`

Result:

Use italics to emphasize information. Use sparingly.

Use bolding for UI elements, dropdown menus, and text contained in a cell.

Alternatively, use emphasis and strong.

And a few others, just in case: _subscript, ^superscript, and title-reference.

Code formatting#

Inline code#

Use fixed width or monospace text for inline code.

Code:

Use ``cd tmp`` to change to the ``tmp`` directory.

Result:

Use cd tmp to change to the tmp directory.

Code blocks#

Use the .. code-block:: directive for blocks of code.

rst#

Code:

.. code-block:: rst

    This is a paragraph split across
    two lines.

Result:

This is a paragraph split across
two lines.

HTML#

Code:

.. code-block:: html

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

Result:

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

YAML#

Code:

.. code-block:: yaml

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

Result:

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

bash#

Code:

.. code-block:: bash

    ls
    pwd
    touch a.txt

Result:

ls
pwd
touch a.txt

python#

Code:

.. code-block:: python

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

Result:

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:

.. code-block:: none

    cat program.py

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

Result:

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:

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

    print('Explicit is better than implicit.')

Result:

this.py#

print('Explicit is better than implicit.')

Lists#

Use #. for ordered (numbered) lists and * for unordered (bulleted) lists.

Ordered lists#

Code:

#. First item
#. Second item

    #. Nested step
    #. Yet another nested step

#. Third item

Result:

First item
Second item
1. Nested step
2. Yet another nested step
Third item

Unordered lists#

Code:

* Begin your list
* Continue your list

  * Use nested lists when appropriate
  * Make sure the spacing and indentations are correct

* Finish your list.

Result:

Begin your list
Continue your list
- Use nested lists when appropriate
- Make sure the spacing and indentations are correct
Finish your list.

Note

If a list item that contains nested lists is auto-bolding erroneously, make sure you’ve added a blank line before and after the nested list.

More complex lists#

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.

Code:

#. 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

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

#. Item 4.

Result:

Item 1.
Item 2.

More text.
1. Part A:
```
command block
```
  OR:
```
alternate command block
```
2. 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
```
Further information can go here. One two three four five six seven eight nine ten.
Item 4.

Links#

reStructuredText supports ordinary links to outside pages. It also has a simpler and more flexible way to link to documents or sections of documents in the current documentation project.

External links#

Code:

Links: http://microsoft.com . `Google <http://google.com>`_.

Results:

Links: http://microsoft.com . Google.

Topic links#

Document links with the :doc: directive send the reader to the beginning of another page.

Code:

See :doc:`the Anaconda documentation <../free/anaconda/index>`.

The link caption defaults to the document title if no other title is given: :doc:`../free/anaconda/index`

Results:

See the Anaconda documentation.

The link caption defaults to the document title if no other title is given: Anaconda Distribution

Section links#

Reference links with the :ref: directive send the reader to another section. The section may be in the current page or another page in the same project. Reference links work like HTML anchor links (such as file.html#section-one) when you place a reference tag before a header: .. _rst-cheatsheet-alpha:.

Code:

See also :ref:`rst-cheatsheet-images` ahead.

Here is a :ref:`link to another section <rst-cheatsheet-images>` up ahead.

Result:

Dropdowns#

Best practices:

Use dropdowns for content-heavy pages (what constitutes as “content-heavy” is left to your discretion) to improve scannability and make the page appear more manageable.
Use concise yet descriptive labels for the dropdown options. Users should be able to anticipate the content before opening the dropdown.

Code:

.. dropdown:: Dropdown title
    :animate: fade-in  # Makes the text fade into picture
    :color: primary  # Makes the dropdown green instead of grey

    Dropdown content

.. dropdown:: Open dropdown
    :color: primary
    :open:  # If for whatever reason you want the dropdown open upon pageload, add this

    Dropdown content

Result:

Tabs#

Best practices:

Tab labels should be concise and use plain language so they are easy to scan. They should be focused to specific sections, rather than encompassing entire topics.
Tabs should be parallel in nature, not so dissimilar as to be mistaken for site navigation.
Tabs should be written in sentence case, not title case or all caps.
Don’t use tabs when content across tabs is sequential.
Don’t use tabs when information needs to be compared or viewed simultaneously (e.g. Package Security Manager features, Data Science & AI Workbench features)

Code:

.. tab-set::

    .. tab-item:: Label1

        A sentence.

        Another one, yet!

    .. tab-item:: Label2

        Content 2

Result:

Label1

A sentence.

Another one, yet!

Label2

Content 2

Tables#

With header#

Code:

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

Result:

a

b

c

north west

north

north east

west

center

east

south

west

south

east

Note the 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.

Without header#

Code:

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

Result:

north west	north	north east
west	center	east
south west	south	south east

Simple tables#

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

Code:

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

Result:

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

CSV tables#

Use the csv-table directive to import a table from CSV (comma-separated value) data.

Tip

Install the Edit csv VSCode extension (Extension ID: janisdd.vscode-edit-csv) to edit .csv files right in VSCode.

Code:

.. csv-table::
   :file: ../csv/sample.csv
   :widths: 30, 25, 35
   :header-rows: 1

Result:

Permission Categories	Available Scopes (category:action)	Associated permissions
Artifacts	artifact:create	Write permissions to parent resource (channel or subchannel)
	artifact:delete	Manage permissions to parent resource (channel or subchannel)
	artifact:download	Read
	artifact:edit	Manage permissions to parent resource (channel or subchannel)
	artifact:view	Read
Channels	channel:create	Write

Admonitions (Notes)#

The documentation currently has four admonition types: notes, tips, cautions, and warnings. This section covers the situations in which these admonitions should be used, based on the advice in the Google developer documentation style guide.

When using admonitions, consider the following:

Use admonitions sparingly. There is evidence that readers skip them.
Avoid grouping two or more admonitions together. If you find it necessary, consider reorganizing the content.

Code:

.. tip::

    A useful aside that might not be as related to the user flow as a note. Might send the user in a different direction.

.. note::

    An ordinary aside. Provides information that is useful, but not critical, and is related to (but not part of) the user workflow.

    - This is how you include lists in a note.
    - Boom, another bullet.

.. caution::

    Tells the user to proceed carefully. Cautions should be used in circumstances where the user will have to redo certain steps or correct mistakes to proceed.

.. warning::

    The strongest admonition. Often used when data loss or a security breach is risked. Use the template, “Don’t do X. Doing X causes Y to happen.”

Result:

Tip

A useful aside that might not be as related to the user flow as a note. Might send the user in a different direction.

Note

An ordinary aside. Provides information that is useful, but not critical, and is related to (but not part of) the user workflow.

This is how you include lists in a note.
Boom, another bullet.

Caution

Tells the user to proceed carefully. Cautions should be used in circumstances where the user will have to redo certain steps or correct mistakes to proceed.

Warning

The strongest admonition. Often used when data loss or a security breach is risked. Use the template, “Don’t do X. Doing X causes Y to happen.”

Inline icons#

Insert inline icons when referencing UI elements with |variables|. These icons are either imported via FontAwesome (if they are icons from any of Anaconda’s web applications, like Anaconda Cloud, Pro, or Package Security Manager) or created using SVG code.

Things to keep in mind:

Name the variable the same thing as the FontAwesome import tag, to make searching for icons easier.
You can look up FontAwesome icons on FontAwesome’s website: https://fontawesome.com/search
In order for icons to switch colors when the Dark/Light theming is toggled, ensure any SVG code does not contain any fill=XXX directives, unless you intend for a unique fill color to overwrite the rules set in the custom.css file.

Code:

From the **Channels** page, click the actions |ellipsis-vertical| icon for your channel.

.. |ellipsis-vertical| raw:: html

   <i class="fa-solid fa-ellipsis-vertical"></i>

Select a new Python Interpreter by clicking the gear |gear| and then clicking **Add**.

.. |gear| raw:: html

    <svg width="16" height="16" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
  <path
    d="M481.9 166.6c3.2 8.7 .5 18.4-6.4 24.6l-30.9 28.1c-7.7 7.1-11.4 17.5-10.9 27.9c.1 2.9 .2 5.8 .2 8.8s-.1 5.9-.2 8.8c-.5 10.5 3.1 20.9 10.9 27.9l30.9 28.1c6.9 6.2 9.6 15.9 6.4 24.6c-4.4 11.9-9.7 23.3-15.8 34.3l-4.7 8.1c-6.6 11-14 21.4-22.1 31.2c-5.9 7.2-15.7 9.6-24.5 6.8l-39.7-12.6c-10-3.2-20.8-1.1-29.7 4.6c-4.9 3.1-9.9 6.1-15.1 8.7c-9.3 4.8-16.5 13.2-18.8 23.4l-8.9 40.7c-2 9.1-9 16.3-18.2 17.8c-13.8 2.3-28 3.5-42.5 3.5s-28.7-1.2-42.5-3.5c-9.2-1.5-16.2-8.7-18.2-17.8l-8.9-40.7c-2.2-10.2-9.5-18.6-18.8-23.4c-5.2-2.7-10.2-5.6-15.1-8.7c-8.8-5.7-19.7-7.8-29.7-4.6L69.1 425.9c-8.8 2.8-18.6 .3-24.5-6.8c-8.1-9.8-15.5-20.2-22.1-31.2l-4.7-8.1c-6.1-11-11.4-22.4-15.8-34.3c-3.2-8.7-.5-18.4 6.4-24.6l30.9-28.1c7.7-7.1 11.4-17.5 10.9-27.9c-.1-2.9-.2-5.8-.2-8.8s.1-5.9 .2-8.8c.5-10.5-3.1-20.9-10.9-27.9L8.4 191.2c-6.9-6.2-9.6-15.9-6.4-24.6c4.4-11.9 9.7-23.3 15.8-34.3l4.7-8.1c6.6-11 14-21.4 22.1-31.2c5.9-7.2 15.7-9.6 24.5-6.8l39.7 12.6c10 3.2 20.8 1.1 29.7-4.6c4.9-3.1 9.9-6.1 15.1-8.7c9.3-4.8 16.5-13.2 18.8-23.4l8.9-40.7c2-9.1 9-16.3 18.2-17.8C213.3 1.2 227.5 0 242 0s28.7 1.2 42.5 3.5c9.2 1.5 16.2 8.7 18.2 17.8l8.9 40.7c2.2 10.2 9.4 18.6 18.8 23.4c5.2 2.7 10.2 5.6 15.1 8.7c8.8 5.7 19.7 7.7 29.7 4.6l39.7-12.6c8.8-2.8 18.6-.3 24.5 6.8c8.1 9.8 15.5 20.2 22.1 31.2l4.7 8.1c6.1 11 11.4 22.4 15.8 34.3zM242 336a80 80 0 1 0 0-160 80 80 0 1 0 0 160z"
  />
</svg>

Click the Anaconda Assistant |assistant| icon to open the Assistant.

.. |assistant| raw:: html

<svg width="16" height="16" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
<path
d="M10.125 3.25C10.0312 3.1875 10 3.09375 10 3C10 2.90625 10.0312 2.84375 10.125 2.78125L12 2L12.75 0.15625C12.8125 0.0625 12.9062 0 13 0C13.0938 0 13.1562 0.0625 13.2188 0.15625L14 2L15.8438 2.78125C15.9375 2.84375 16 2.90625 16 3C16 3.09375 15.9375 3.1875 15.8438 3.25L14 4L13.2188 5.875C13.1562 5.96875 13.0938 6 13 6C12.9062 6 12.8125 5.96875 12.75 5.875L12 4L10.125 3.25ZM15.8438 12.7812C15.9375 12.8438 16 12.9062 16 13C16 13.0938 15.9375 13.1875 15.8438 13.25L14 14L13.2188 15.875C13.1562 15.9688 13.0938 16 13 16C12.9062 16 12.8125 15.9688 12.75 15.875L12 14L10.125 13.25C10.0312 13.1875 10 13.0938 10 13C10 12.9062 10.0312 12.8438 10.125 12.7812L12 12L12.75 10.1562C12.8125 10.0625 12.9062 10 13 10C13.0938 10 13.1562 10.0625 13.2188 10.1562L14 12L15.8438 12.7812ZM12 8C12 8.1875 11.875 8.375 11.7188 8.4375L8.1875 10.2188L6.4375 13.75C6.34375 13.9062 6.15625 14 6 14C5.78125 14 5.625 13.9062 5.53125 13.75L3.78125 10.2188L0.25 8.4375C0.09375 8.375 0 8.1875 0 8C0 7.8125 0.09375 7.625 0.25 7.5625L3.78125 5.78125L5.53125 2.28125C5.71875 1.9375 6.25 1.9375 6.4375 2.28125L8.1875 5.78125L11.7188 7.5625C11.875 7.625 12 7.8125 12 8Z"
fill="#31a824"
/>
</svg>

# Note the fill="#31a824" at the end of the Assistant icon's path tag. This will ensure the icon stays green.

Results:

From the Channels page, click the actions icon for your channel.

Select a new Python Interpreter by clicking the gear and then clicking Add.

Click the Anaconda Assistant icon to open the Assistant.

Images#

Insert images with the .. thumbnail:: directive.

Code:

.. thumbnail:: /img/rst-cheatsheet-earth.jpg
   :align: center

   Caption goes here.

Start typing your next sentence here.

Result:

Start typing your next sentence here.

Comments in code#

Comments can be great for providing details for other writers internally.

You’ll see them most often in CSS files, like the custom.css file that dictates our copy style. Those comments look like this:

/* Switches fills for in-line SVG icons when switching between light/dark mode. */

It’s possible to comment in reStructuredText files as well, though it is rare to see. This can be done like this:

.. This is a comment.

..
    This whole indented line is also a comment.

    Still in the comment.

This line is not part of the commented out lines. Note how you do not see any sentences between the code block above and this line, as you are viewing the published file.

This line is not part of the commented out lines. Note how you do not see any sentences between the code block above and this line, as you are viewing the published file.

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. Ensure the files have unique names.

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

Unicode#

Registered trademark#

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 an “escaped space” by typing a backslash and then a space (word\ |reg|).

For example, Anaconda®

Copyright#

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 an escaped space by typing a backslash and then a space (Copyright\ |copy|).

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>

Redirects#

The Anaconda docs use the sphinx-reredirects extension for most of its redirects. Any folder-level redirects are still handled by the ReadTheDocs backend.

The formatting for the sphinx-reredirects redirects is slightly different depending on whether the documentation is a dirhtml build (alldocs) or an html build (Server and Enterprise docs).

Redirect formatting for dirhtml

For dirhtml builds of the documentation (i.e. docs where the URL ends in a / instead of a .html), make sure you add a / to the end of the new URL in the redirect.

Also make sure that you add the same number of ../ directory changes as the number of directories in the first file path in the redirect.

"path/to/old/rst/file": "../../../../../path/to/new/URL/"

# For example

"anaconda/getting-started/install/linux": "../../../../free/anaconda/install/linux/"

Redirect formatting for html

For html build of the documentation (i.e. docs where the URL ends in .html), make sure you add a .html to the end of the new URL in the redirect.

Also make sure that you add the same number of ../ directory changes minus one as the number of directories in the first file path in the redirect.

"path/to/old/rst/file": "../../../../path/to/new/URL.html"

# For example

"install/uninstall": "../admin/uninstall.html",

For more information on the sphinx-reredirects extension, see the sphinx-reredirects documentation.

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