Table Of Contents

Previous topic

Download Helper Files

Next topic

Markdown Syntax

This Page

Re-Structured Text Syntax


The following guide to reST and Sphinx markup is intended to be helpful but not exhaustive. More comprehensive and less comprehendable documentation is available from official Sphinx sources. [1]


At the top of each reST document is a title surrounded with markers: [2]

A Document Title Goes Here

Each document section or subsection is indicated with an underlined heading:

This is a heading

And so this is a sub-heading

Page break lines are inserted with a series of dashes



Paragraphs are indicated by entering two newlines, which shows as a blank line in the text. Single newlines are ignored except in lists or other directives.

When using a text editor, lines are typically broken by newline characters and word wrapping is not performed. This corresponds to programming practice, where each statement of a program is marked by a newline.

Inline Style Formatting

The following table displays inline or embedded markups for text styles:

Markup Result
*italicized text* italicized text
**bold text** bold text
`emphasized text` emphasized text
``unformatted text`` unformatted text

Inline Markup Directives


Inline Markup Directives are supported in Sphinx but not in basic reST. Therefore these commands will generate errors in the interactive editor at

Markup Result
:kbd:`text` text
:guilabel:`text` text
:menuselection:`menu –> item` menu ‣ item
:command:`git add .` git add .
:file:`../path/to/file` ../path/to/file
:download:`script <>` script
:ref:`Tables <tables_label>` Tables


Build table layouts as shown below:

| Markup                             | Result                         |
| \:kbd\:\`text\`                    | :kbd:`text`                    |
| \:guilabel\:\`text\`               | :guilabel:`text`               |
| \:menuselection\:\`menu --> item\` | :menuselection:`menu --> item` |
| \:command\:\`git add .\`           | :command:`git add .`           |

List Entries

| The Pipe symbol starts a separate text line.
| Use this for simple lists.
The Pipe symbol starts a separate text line.
Use this for simple lists.
+ Plus or minus signs start bulleted items.
+ Use this for item lists.
  • Plus or minus signs start bulleted items.
  • Use this for item lists.
#. Hash-dot starts a numbered line.
#. Use this for numbered lists.
  1. Hash-dot starts a numbered line.
  2. Use this for numbered lists.

When a paragraph ends with a double colon (::):

Following indented lines are blocked.
Use this for code examples.

Indent lists with spaces or tabs to indent the displayed text:

Indent lists with spaces or tabs to indent the displayed text:

Additionally indented lines are blocked.
Use this for code examples.


When the double-colon is preceded with a space, no colon shows in the output.

Paragraph Directives

The following directives should be followed by an indented paragraph of text. The text will appear in a message window, a sidebar, or otherwise set off from the main document text.

:: The following paragraph will display as unformatted code.

.. [#] This paragraph is a footnote paired with a text reference. [#]_

.. tip :: This paragraph is the text of a short tip.

.. hint :: This paragraph is a hint.

.. note :: This paragraph is the text of a note.

.. warning :: This paragraph is (not) a warning.

.. sidebar :: The following (titled) paragraph will appear in a sidebar.

.. rubric :: This heading is not in the Table of Contents.

.. centered :: THIS TEXT IS CENTERED.


[1]Sphinx documentation.
[2]Characters for marking headings are arbitrarily set within a project by usage. This is an example of simplifing a task by Convention over Configuration.

RST Publication Structuring

RST features extend beyond document markup to provide for structuring multiple document pages into sections, chapters, and entire publications or books. AAltsys scripts (,, and manage git repositories of RST documents with multiple section folders, where indexing and referencing between sections is expected. Follow this guide to setup a document project in multiple sections.

Identify Document Sections

To create a document with chapters or sections, begin by creating a folder in ~Projects to hold the entire project. Within this folder, edit text file sections, entering one-word section names on consecutive lines. If your project will contain referenced material such as appendices, then make a resource section at the top of the list. The final line should be section master, which will contain the project master index. So the sections text will look like:


Create New Project

From within the project folder, run the script command:


This script will initialize a Sphinxdoc folder for each listed chapter section. Sphinx will prompt you to use InterSphinx for each folder, and always answer yes. The script will link all the projects together in the master section. However, the link statements will be missing in other sections. Later, you may need to reorganize the section compilation order, that is, reorder the section list, and add InterSphinx Mapping commands to the program in the section folders.

InterSphinx Mapping

For the project section list previously mentioned, the master folder would contain a program ending in the following statement:

intersphinx_mapping = {
   'resources': ('resources', '../_deploy/resources/objects.inv'),
   'chapter01': ('chapter01', '../_deploy/chapter01/objects.inv'),
   'chapter02': ('chapter02', '../_deploy/chapter02/objects.inv'),
   'chapter03': ('chapter03', '../_deploy/chapter03/objects.inv'),

Creating references between sections requires entering similar statements in programs for other chapters, with subtle differences. Suppose chapter02 needs to reference labels in resources and chapter01. Then the mapping statement at the end of its should read:

intersphinx_mapping = {
   'resources': ('../resources', '../_deploy/resources/objects.inv'),
   'chapter01': ('../chapter01', '../_deploy/chapter01/objects.inv'),

Notice that for the chapters, the internal mapping names begin with a folder dereference (../). This is not necessary for the master section because the compilation script moves this one index folder out one level when building the project deployment files.


Documentation for chapter02 is compiled preceding chapter03. Therefore Chapter02 will not be able to reference chapter03, and adding chapter03 to the mapping in chapter02 will trigger a compilation error message.

Section Index Documents

Each chapter section of a document will contain an index.rst file. The directives in each index file except master should be organized as follows:

.. _index:

Chapter or Section Title

.. toctree::
   :maxdepth: 2


There may be other text, comments, or directives in the index page as well, of course.


In this example, a :glob: directive is used to automatically accumulate documentation files into an index. :glob: requires a further parameter indicating the files to be collected, the [0-9]* above. This will collect all documents starting with a number, in sorted sequence.

Master Index Document

The index.rst file in the master section requires a hand-compiled table of contents for the project chapters:

.. _index:

Master Document Title

#. :ref:`chapter01:index`.
#. :ref:`chapter02:index`.
#. :ref:`chapter03:index`.
#. :ref:`resources:index`.

Again, other text and formatting directives may be included to fill out this page.

Master Index Back References

Since sections are compiled before the master document, there is no way for a chapter or section to contain an internal reference to the corresponding master index. The script can fix this by editing deployed index.html pages, replacing the “here links” at the top and bottom of section index pages with external references to the corresponding project master index page.

Implement this feature by adding a document named backreference in the _static folder with the desired html link, such as:

<a class="external reference" href="../index.html">AAltsys Development Main Index</a>

Similar to section index backlinks, will add navigation links to source URLs. This is helpful when multiple projects are published as subdomains of an apex domain containing a documentation index page.

Add these links with a master/_static/backreference document in any multi-section project, or with a _static/backreference document in other projects. The html link format should look like:

<a href="">AAltsys Information Master Index</a>

Obviously you should use your own text to replace the “” domain name and the corresponding titles.

Tip inserts back reference links in folder _deploy. The compiler output in _build within chapters is unchanged.