Note
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.
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 |
Note
Inline Markup Directives are supported in Sphinx but not in basic reST. Therefore these commands will generate errors in the interactive editor at http://rst.ninjs.org.
| 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 <path.sh>` | 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 .` |
+------------------------------------+--------------------------------+
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.
Hint
When the double-colon is preceded with a space, no colon shows in the output.
.. _label_reference:
.. image :: `_images/04_self-publish_new.png`
[#]_ (footnote number insertion)
`Online reST Editor <http://rst.ninjs.org/>`_
Tip
The underscore preceding “label_reference” is part of the directive, not part of the label. The same is true for the underscore following footnote brackets, and the underscore following a URL link.
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.
Footnotes
| [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 features extend beyond document markup to provide for structuring multiple document pages into sections, chapters, and entire publications or books. AAltsys scripts (doc-newproject.sh, doc-deploy.sh, and doc-addproject.sh) 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.
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:
resources
chapter01
chapter02
chapter03
master
From within the project folder, run the script command:
../doc-newproject.sh
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 doc-newproject.sh 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 conf.py program in the section folders.
For the project section list previously mentioned, the master folder would contain a conf.py 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 conf.py 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 conf.py 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.
Note
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.
Sphinxdoc markup provides for linking references to labels within a document. Where labels precede a heading, the reference will be replaced with the section heading text by default. Labels are entered as directives on blank lines, as shown following. Note that label directives start with .. _ and end with :, as in:
.. _mylabel:
Use the :ref: inline markup directive to reference a label within a document. For example, the directive :ref:`pubstructure` would take you to RST Publication Structuring at the start of this article.
By extension, a label in another chapter section of a project is referenced by adding the section name into the directive, as for example:
:ref:`resources:mylabel`
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
:glob:
[0-9]*
There may be other text, comments, or directives in the index page as well, of course.
Note
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.
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.
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 doc-deploy.sh 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, doc-deploy.sh 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="http://aaltsys.info">AAltsys Information Master Index</a>
Obviously you should use your own text to replace the “aaltsys.info” domain name and the corresponding titles.
Tip
doc-deploy.sh inserts back reference links in folder _deploy. The compiler output in _build within chapters is unchanged.