Sphinx Help

Markup • Roles • Directives • Topics • External Links

Topics

Docutils Markup
Titles/Sections
Paragraph
Lists
    Bullet
    Enumerated
    Definition
Block Quotes
Comments
Line Blocks (single spacing)
Literal Blocks
Footnotes
Emphasis (italic)
Strong Emphasis (bold)
Escaping



An ICG Doc
Titles
Sections/Rubrics
Links
Tables
Lists
Images & Figures
Inclusions (rst)
Inclusions (data files)
Spacing (Less & More)
Comments
Footnotes/Sidenotes

Anatomy: Command doc
Anatomy: FISH doc
Anatomy: Example doc
Anatomy: Index doc
The linked topics under the “Docutils Markup” go to the core documentation for reST. The linked topics under “An ICG Doc” go to docs here that give additional information on usage and implementation as seen in ICG doc sets. There is not a one-to-one correspondence between topics.
Table 4: Topics
Topic Link
Working with toctrees Toctree Tips
Finding icon images where the icons are
Code snippets code snippets
Notes & Footnotes notes and footnotes
Latex math tips latex math tips
Dave P’s Notes David P’s sphinx notes
Repeat Blocks how to construct a repeat block
Note: this Topics “tab” is being eliminated. Content on the table is in process of being folded into other topics/tabs. If you are looking for a topic that was previously here, it has likely moved to the “An ICG Doc” column of the “Markup” tab.
Table 5: External Links
Content Address
Sphinx home http://www.sphinx-doc.org
reST home http://docutils.sourceforge.net/rst.html
Sphinx directives, by category http://www.sphinx-doc.org/en/stable/rest.html#directives
reST/Sphinx in one (long) page http://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html
notepad++ wiki http://docs.notepad-plus-plus.org
unicode page Unicode Characters

The Sphinx System, In Brief

The Sphinx system used for Itasca’s documentation comprises three major components (plus a bunch of other bits too).

  • The Python package Docutils, which interprets reST (restructured text, *.rst) markup, produces single documents in a variety of possible output formats.
  • The Python package Sphinx, which extends Docutils, is what Python uses to document itself. It allows for the creation of multiple-document sets and hyperlinking between documents, among many things.
  • The Itasca extension to Sphinx handles the specific case of Itasca code commands and FISH and a few other customizations.

reST markup takes one of three forms: plain markup, a directive, or a role. All are tabled above. All plain markup comes from Docutils exclusively; Sphinx and Itasca additions always take the form of either a directive or a role. On the directives and roles tables above, the column headings indicate which Sphinx system component provides them. Hyperlinks are provided to go to source documentation.

Markup, Directives, Roles

  • Markup is used for both block-level and inline constructions.
  • Directives are almost always for block-level constructions (figures, tables, sections, etc.)
  • Roles are typically for inline formatting (italicization, bold, special character formatting, etc.).

Almost all directives take what reST calls “options.” So, for instance, the .. image:: directive has the options :alt: , :height: , :width: , :scale: , :align: , :target: . Refer to the documentation for the directive to see its arguments and how they may be used.

reST Markup Cautions

  1. reST is very simple, but the division of labor between what is done directly in markup and what is done via role or directive is not necessarily inherently obvious. For instance, it would make sense conceptually to have a :title: role, but there isn’t one; nor is there a .. paragraph:: directive. These and other jobs are done solely in markup. Second, straight markup tasks do not come with handy “names” like roles and directives, so it is sometimes harder to “find” them when looking for how to do things. Last, there are a few cases (italicization, for instance) where markup and a role can be used to do the same thing.
  2. reST is heavily reliant on white space, horizontally and vertically. Unfortunately, there is no discernible rationale that can be used to anticipate when it will interpret white space and when it will ignore it — and it does both. In other words, there will be times when correct white space handling is critical for the current markup (see bullet lists, for instance) and other times when it doesn’t mean anything. If your output doesn’t look like what you think it should, there is an outstanding chance that mishandling of white space has caused the problem.

If you’ve read all the way down to here and have a feel for everything you’ve seen so far, you’re probably ready to go over Sphinx Day One next.