Detailed reStructuredText and Sphinx example file
=================================================

.. contents::
   :local:

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

General formatting
------------------

.. code-block:: rst

    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.

.. code-block:: rst

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

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


.. code-block:: rst

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

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


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

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 |reg| or (R) with a space before and after the symbol, 
first insert this line at the bottom of the file:

.. code-block:: rst

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

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

.. code-block:: rst

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

abc--def |reg| 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\ |reg|

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

.. code-block:: rst

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

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

.. code-block:: rst

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

abc--def |copy| 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\ |copy| 2017, Anaconda, Inc.


Lists and indentation
---------------------

.. code-block:: rst

    * bullet list
    * with a very long second item 
      on two lines.

* bullet list
* with a very long second item 
  on two lines.


.. code-block:: rst

    1. numbered
    2. list

1. numbered
2. list


.. code-block:: rst

    #. another numbered
    #. list

#. another numbered
#. list


.. code-block:: rst

    * bullet
    * list

      * with
      * nesting

    * which then continues


* bullet
* list

  * with
  * nesting

* which then continues


.. code-block:: rst

    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.

.. This is a comment.

..
    This whole indented block
    is a comment.

    Still in the comment.

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.

.. code-block:: rst

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

    .. code-block:: rst

        This is a paragraph split across
        two lines.


.. code-block:: rst

    This is a paragraph split across
    two lines.

HTML
^^^^

.. code-block:: rst

    .. code-block:: html

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


.. code-block:: html

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


YAML
^^^^

.. code-block:: rst

    .. code-block:: yaml

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


.. code-block:: yaml

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


bash
^^^^

.. code-block:: rst

    .. code-block:: bash

        ls
        pwd
        touch a.txt

.. code-block:: bash

    ls
    pwd
    touch a.txt


python
^^^^^^

.. code-block:: rst

    .. code-block:: python

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

.. code-block:: python

    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:: rst

    .. code-block:: none

        cat program.py

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

.. code-block:: none

    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:: rst

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

        print('Explicit is better than implicit.')

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

    print('Explicit is better than implicit.')

Tables
------

Grid table with header:

.. code-block:: rst

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

+----------+-----------+-------+
| a        | b         | c     |
+==========+===========+=======+
| north    | north     | north |
| west     |           | east  |
+----------+-----------+-------+
| west     | center    | east  |
+----------+-----------+-------+
| south    | south     | south |
|          |           |       |
| west     |           | 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:

.. code-block:: rst

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

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

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

.. code-block:: rst

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

.. code-block:: rst

    http://microsoft.com

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

    This paragraph links to `the yahoo site`_.

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

http://microsoft.com

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

This paragraph links to `the yahoo site`_.

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

Table of contents
-----------------

.. code-block:: rst

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

.. code-block:: rst

    .. contents::
        :local:


Another file might use this table of contents:

.. code-block:: rst

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

.. code-block:: rst

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

.. code-block:: rst

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

.. code-block:: rst

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

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

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.

.. code-block:: rst

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

Notes
-----

.. code-block:: rst

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

.. code-block:: rst

    .. raw:: html

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

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

.. |reg|    unicode:: U+000AE .. REGISTERED SIGN
.. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
