reStructuredText basics

The base language for this website is reStructuredText (RST). It is used to produce documents with formatted text, similar to the language markdown. RST documents are built into HTML web pages with the help of Sphinx, a document generator.

RST Syntax

Plain text

In RST, lines of code that are not formatted will be displayed as text. Long lines of text will be wrapped into a single paragraph when rendered.

RST

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at ultrices magna, ac volutpat nisi. Sed sed finibus libero, eget luctus massa. Praesent pulvinar orci in metus mollis consectetur. Integer gravida dolor ut quam efficitur euismod. Phasellus vitae elementum massa. Praesent volutpat sed purus id mollis. Maecenas sit amet libero ac mauris porta mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur augue hendrerit at.

Output

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at ultrices magna, ac volutpat nisi. Sed sed finibus libero, eget luctus massa. Praesent pulvinar orci in metus mollis consectetur. Integer gravida dolor ut quam efficitur euismod. Phasellus vitae elementum massa. Praesent volutpat sed purus id mollis. Maecenas sit amet libero ac mauris porta mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur augue hendrerit at.

In addition, subsequent lines of text will be considered one paragraph, as well. This is to enhance readability of the RST files.

RST

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec at ultrices magna, ac volutpat nisi. Sed sed finibus
libero, eget luctus massa. Praesent pulvinar orci in metus
mollis consectetur. Integer gravida dolor ut quam efficitur
euismod. Phasellus vitae elementum massa. Praesent volutpat
sed purus id mollis. Maecenas sit amet libero ac mauris porta
mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada
pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur
augue hendrerit at.

Output

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at ultrices magna, ac volutpat nisi. Sed sed finibus libero, eget luctus massa. Praesent pulvinar orci in metus mollis consectetur. Integer gravida dolor ut quam efficitur euismod. Phasellus vitae elementum massa. Praesent volutpat sed purus id mollis. Maecenas sit amet libero ac mauris porta mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur augue hendrerit at.

If you separate lines of text with blank lines in between, this creates a new paragraph.

RST

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec at ultrices magna, ac volutpat nisi. Sed sed finibus
libero, eget luctus massa. Praesent pulvinar orci in metus
mollis consectetur. Integer gravida dolor ut quam efficitur
euismod.

Phasellus vitae elementum massa. Praesent volutpat
sed purus id mollis. Maecenas sit amet libero ac mauris porta
mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada
pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur
augue hendrerit at.

Output

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at ultrices magna, ac volutpat nisi. Sed sed finibus libero, eget luctus massa. Praesent pulvinar orci in metus mollis consectetur. Integer gravida dolor ut quam efficitur euismod.

Phasellus vitae elementum massa. Praesent volutpat sed purus id mollis. Maecenas sit amet libero ac mauris porta mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur augue hendrerit at.

Headers and titles

RST has the ability to make headers in your document by underlining text with different characters.

RST

My header
=========

Titles can also be made with underling and overlining equals signs.

RST

========
My Title
========

Please visit the documentation for more information on headings.

In-line text formatting

Any text can be formatted to be italic, bold, or as in-line code.

RST

*italics*

**bold**

``inline code``

Output

italics

bold

inline code

You can also make bulleted and numbered lists. If you would like to put an entry on two adjacent lines for visual clarity, make sure the second line is tabbed over to start at the same horizontal location as the previous line.

RST

-  Small bullet
-  Multi-line
   bullet point
-  Small bullet

1. Number 1
2. Number 2
   is longer
3. Number 3

Output

• Small bullet

• Multi-line bullet point

• Small bullet

1. Number 1

2. Number 2 is longer

3. Number 3

You can also do sub-bullets with additional tabbing.

RST

-  Main bullet
    -  sub bullet
- Another main bullet

Output

• Main bullet

  • sub bullet

• Another main bullet

Directives

Some formatted text requires using a directive. This is a way to denote a block of code for a specific purpose. There are some built-in directives, but also many from extensions that we will use. .. code::, for instance, creates a code block with highlighting of the specified language.

RST

.. code:: python

    def my_func():
        print('hello world')

Output

def my_func():
    print('hello world')

There are many codecs you can use for code highlighting, which you can view here.

Similarly, sphinx_inline_tabs gives access to the .. tab:: directive. This is commonly used throughout this site to display code and output. The text following the directive will be used as the name on the tab.

RST

.. tab:: First tab

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Donec at ultrices magna, ac volutpat nisi. Sed sed finibus
    libero, eget luctus massa. Praesent pulvinar orci in metus
    mollis consectetur. Integer gravida dolor ut quam efficitur
    euismod.

.. tab:: Second tab

    Phasellus vitae elementum massa. Praesent volutpat
    sed purus id mollis. Maecenas sit amet libero ac mauris porta
    mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada
    pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur
    augue hendrerit at.

Output

First tab

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at ultrices magna, ac volutpat nisi. Sed sed finibus libero, eget luctus massa. Praesent pulvinar orci in metus mollis consectetur. Integer gravida dolor ut quam efficitur euismod.

Second tab

Phasellus vitae elementum massa. Praesent volutpat sed purus id mollis. Maecenas sit amet libero ac mauris porta mattis. Nam at ullamcorper nulla. Donec eu leo eu nunc malesuada pharetra id ac justo. Nulla facilisis magna ante, vitae consectetur augue hendrerit at.

The spacing and tabbing here is important. Any named arguments must come on the next line after the directive and tabbed over. Any content in the directive has to be tabbed over and have a blank line after the directive and arguments. Nested directives also follow this pattern.

RST

.. tab:: Python

    .. code:: python

        print('hello world')

.. tab:: Output

    .. code:: none

        hello world

Output

Python

print('hello world')

Output

hello world

If you have two sets of tabs one after the other, you can use the :new-set: argument to separte the sets of tabs.

RST

.. tab:: Python

    .. code:: python

        print('hello world')

.. tab:: Output

    .. code:: none

        hello world

.. tab:: Python
    :new-set:

    .. code:: python

        print(2 + 4)

.. tab:: Output

    .. code:: none

        6

Output

Python

print('hello world')

Output

hello world

Python

print(2 + 4)

Output

6

Toctree

One of the most important directives is the toctree - the table of contents tree. It defines the structure of the website and how different documents relate to each other. The navigation on the left-hand side of the website is determined by the toctrees present in different documents. Every document must be listed in another document’s toctree to appear in the navigation.

This is the toctree of index.rst, the base page of the website:

.. toctree::
    :hidden:
    :maxdepth: 2
    :caption: Contents:

    python
    R <r>
    shell
    git
    sql
    Contribute to DeisData <contribute>

The toctree directive here has 3 specified parameters. :hidden: means that the toctree will only be displayed in the page navigation and not in the main body of the document. :maxdepth: 2 means that the displayed toctree will show 2 levels deep. For instance index.rst contains python.rst in its toctree, which contains setup-install.rst in its toctree. If setup-install.rst had documents in its toctree, these would not be displayed, as that would be a depth of 3. :caption: Contents: right now is not doing anything because the toctree is hidden, but if it were not, this would be the title of it in the document.

Underneath the arguments are documents we want to include in the toctree. The names specified are the names of the documents without the .rst file extension. In the navigation, the name specified will be the title of that document. If you would like to use a different name, you can write the name you prefer and include the name of the document afterwards in angle brackets -> Contribute to DeisData <contribute>.

If the document is in a subdirectory of source, like the python directory, you’ll need to specify the relative path to the document from the source directory. For example, to add the setup-install.rst document, you’ll need to specify python/setup-install. Sometimes, adding a leading slash is necessary /python/setup-install depending on the directory.

Links

In RST, we separate links into two categories: external references and internal references. External references can go to any URL and are a little simpler.

RST

Check out `this link <https://en.wikipedia.org/wiki/Main_Page>`__.

Output

Check out this link.

Internal references, on the other hand, are used to link to other documents or to other labeled points of interest on any given document. When linking to documents you can specify the document you want to like to with :doc:`docname`.

RST

For more on Python, check out our :doc:`installation guide </python/setup-install>`.

Output

For more on Python, check out our installation guide.

We can also make links to internal headings or any other places of interest.

RST

.. _test reference:

Some text to reference.

This points to :ref:`the test reference <test reference>`.

Images

You can also include images or figures through a couple of different methods, including using the .. figure: directive.

RST

.. figure:: /_static/images/contribute/cat.jpeg
    :alt: cat pic

Output

In our directory structure, images are stored in the source/_static/images directory.

You can also include images with the .. image:: directive. In several documents, we use this approach combined with tagging with |image tag name| to refer to images.

RST

|cat image|

.. |cat image| image:: /_static/images/contribute/cat.jpeg

Documentation

Please view the Sphinx primer on RST for more information.