Detailed reStructuredText and Sphinx example file — Anaconda Enterprise 4.4 documentation

Anaconda Enterprise: Documentation

# Detailed reStructuredText and Sphinx example file

- General formatting
- Smart quotes, dashes, and Unicode
- Lists and indentation
- More complex lists and indentation
- Code blocks
  - rst
  - HTML
  - YAML
  - bash
  - python
  - none
  - Captions
- Tables
- Links
- Table of contents
- Index files
- Images
- Downloadable files
- Notes
- YouTube videos (and other raw html in rst files)
- More information

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.

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

## Links

    http://microsoft.com

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

    This paragraph links to `the yahoo site`_.

    .. _the yahoo site: http://yahoo.com/

http://microsoft.com

Google

This paragraph links to the yahoo site.

## Table of contents

    .. contents::

Contents

- Detailed reStructuredText and Sphinx example file
  - General formatting
  - Smart quotes, dashes, and Unicode
  - Lists and indentation
  - More complex lists and indentation
  - Code blocks
    - rst
    - HTML
    - YAML
    - bash
    - python
    - none
    - Captions
  - Tables
  - Links
  - Table of contents
  - Index files
  - Images
  - Downloadable files
  - Notes
  - YouTube videos (and other raw html in rst files)
  - More information

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.

## Downloadable files

Files marked for download will be copied from their place in the source directory to build/html/_downloads , and duplicate filenames are handled.

    See :download:`this example script <../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