Internal Documentation Resources¶

This is a guide for formatting your content with reStructuredText in Sphinx. A textual data format developed by the Docutils project as a documentation tool for Python. The installation of this documentation site can be found in the project’s readme.md file, this page is solely intended for teaching the basics of Sphinx and reStructuredText and provide you with links for further documentation and guides for the more complex stuff.

Creating Python extensions to extend, modify or disable any function of the rST pre-processor is out of scope for this guide, we will only cover the basic configuration parameters for modifying the content of the base furo template (such as title, logo, copyright etc.) and where else to replace them in the static files where reading those values is not possible due to Sphinx’s internal rendering logic (404 error page etc.) and the content-tree and formatting within Sphinx itself.

This guide will refer to blocks of content either as “block(s)“ or “node(s)“ depending on the context, they refer to any type of content found in reStructuredText that follow the same syntax.

The guide will also use the words “parent(s)“ and “child(ren)“ to refer to content nodes/blocks embedded into each other.

Now: Let’s get through the most important bits

White spaces and Indentation¶

It’s a Python based framework after all…

Important

Indentation and spacing is critical for reStructuredText documents. Unless otherwise stated, always use two spaces for indentation, and always leave an empty line between content blocks.

For inline formatting, such as **bold** or *italic* text, `links <...>`_, note that they cannot be combined, you cannot emphasize a link or part of a link etc. And you must leave white space around them. If you want to remove the white space around an element, you must escape them with dashes:

This is a re\ **Structured**\ Text example

Result: This is a reStructuredText example.

Otherwise they won’t render as intended.

Directives and the TOC-tree¶

One of Sphinx’s main feature is the dynamically generated document-tree, which collects data from Sphinx’s toctree directive, and builds the links based on them. The directory and link structure is completely ignored in the process, you need to add the main links to your index.rst document in the root of your source page. And it will also serve as the landing page of the documentation site.

Note

This is that page.

Another compelling feature of reStructuredText is that you can define “directives“ via plugins and extensions on top of Sphinx’s main ones, which can handle content for you in various different ways. We will cover the most important default ones and the general directives syntax in this guide.

TOC-tree¶

As mentioned you need to add the toctree to your index.rst document, it can be placed anywhere you’d be happy to render it within the page. You can add it to your document after the title, or the end of it, or anything in-between.

Caution

The document title has to be the first thing in your document after the optional meta tags, or the page won’t be rendered and added to your TOC-tree.

The syntax of the toctree directive is as follows:

.. toctree::
  :maxdepth: N
  :caption: Optional Title for your TOC

  pages-in-the-order
  youd-like-to
  show-them

The :caption: variable is optional, it will be shown as the heading of the contents. The :maxdepth: variable will tell Sphinx how deep the list should be rendered out, if it is shown in the content.

The :maxdepth: variable is ignored in the side-bar, it will always show every added item in the side-bar menu. It is only relevant to the page’s rendered content.

Alternatively, you can also add the :hidden: variable to the TOC-tree, so that it won’t render on the page itself.

.. toctree::
  :hidden:

  pages-to-add
  to-the-menu

Important

The content of the toctree directive takes both relative and absolute paths (using the source folder as root), watch out for those slashes at the beginning of the file names.

The best practice is to have your directroy structure follow your intended menu layout and add only the files in the folder named after your page. This will avoid confusion and recursion errors.

Important

Once again, the :maxdepth: and :hidden: variables don’t affect what is shown in the side-bar. The only way to hide a page from the menu is to not add it to the DOC-tree at all, and link to it via the :doc: role instead.

Warning

DO NOT CROSS-REFERENCE IN THE TOC-TREE! AND NEVER ADD THE INDEX FILE ITSELF TO IT!

It will create an infinite loop resulting in a recursion error and break the page rendering, as Sphinx offers no protection against it other than stopping it completely. NEVER DO SOMETHING LIKE THIS:

tools.rst

.. toctree::
  :hidden:

  tools/backup
  tools/recovery
  tutorials

tutorials.rst

.. toctree::
  :hidden:

  tutorials/backup
  tutorials/recovery
  tools

Adding the same entry to multiple paths, even if it doesn’t cause an error, it will still cause the side-bar to treat the first occuring entry as the highlighted menu entry, regardless of the path taken to open it. It will also open up all other sub-menus that contain the item.

Directives and Syntax¶

Directives are the main way you can use Sphinx’s more advanced content formattings and interactive content.

Every directive is hard-coded into Sphinx (or its plugins and extensions), and they follow the same format:

.. DIRECTIVE::
  :VARIABLE: VALUE(S)
  :VARIABLE: VALUE(S)

  CONTENT

Alternatively, if the directive takes a single variable, only its values need to be defined:

.. DIRECTIVE:: VALUE(S)

  CONTENT

As each directive needs to be properly indented, all of them are handled as blocks, so in order to use them inline (such as a custom image that you want to use as an icon) you must create a reference point at the bottom of your document, and embed the reference in the content. Similarly how footnotes and referenced links work in Markdown.

You can read about them in the following section.

Further information on Sphinx and rST¶

This covers the basic information in the following topics:

Contents

Footnotes