Sphinx Help

Show:       ICG Usage Markup   Roles    Directives   
Table 1: Docutils Markup Documentation

Titles/Sections

Paragraph

Lists: Bullet

Lists: Enumerated

Definition

Block Quotes

Comments

Line Blocks (single spacing)

Literal Blocks

Footnotes

Emphasis (italic)

Strong Emphasis (bold)

Escaping

Substitution

The Sphinx System, In Brief

The Sphinx system used for Itasca’s documentation comprises three major components (plus extensions and other ancillary matter).

  • 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, an extension of 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 (type something a certain way to get a certain result)

  • directive (takes the form .. directive:: directive content)

  • role (takes the from :role:ˋrole contentˋ)

All are tabled above. All plain markup comes from Docutils exclusively. The Sphinx and Itasca extensions 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. For instance:

    Document Title
##############

"Underlining" with "#" builds a document title. This is block-level.
Inline use of asterisks around content *will produce italicization.*

  • Directives are almost always for block-level constructions (figures, tables, sections, etc.). They always take a base form (.. directive:: directive content) and may include one or more options (:option: value) below them and exactly aligned with the first letter of the directive name. Options are exactly that: optional. Each directive uses defaults when options aren’t supplied. For example, an image:

    .. image:: \path\path\imagefile.png
   :alt: This is the alt text for screen readers
   :height: 80
   :width: 90
   :scale: 50
   :align: center
   :target: blank

  • Roles are typically for inline formatting (italicization, bold, special character formatting, hyperlinks, etc.). They always take the form from :role:ˋrole contentˋ.

    In the course of this paragraph, :emphasis:`italicization` uses the
Docutils role (which, note, could also be done simply with
asterisks), :ref:`a hyperlink <hyperlinksinsphinx>` is built with a
Sphinx role, and achieving :bi:`bold-italic` is done with the
Itasca-built custom role.

reST Markup Cautions

  1. reST is very simple, but the division of labor between what is done by markup and what is done via role or directive is not necessarily inherently obvious. For instance, one might anticipate that there is either a :title: role or a .. title:: directive for declaring a document title, but there isn’t one; nor is there a .. paragraph:: directive. These and other jobs are done solely in markup.

    Second, markup tasks do not come with handy names like roles and directives, so it is sometimes harder to find documentation on them. Last, there are a few cases (italicization, for instance) where markup or a role can be used to do the same thing.

  2. reST is heavily reliant on white space, horizontally and vertically. Unfortunately, it requires great familiarity with the whole system to regularly discern when white space will be interpreted and when it will be ignored — and the system does do both. Sometimes whitespace is critical (see bullet lists, for instance), and other times it doesn’t mean anything. If your output doesn’t look like what you think it should, there is an excellent chance that mishandling of white space has caused the problem.

Ready to Build

To build documents, in the console of your choice go to the doc set’s “docproject” folder. For wad9, for instance, go to:

[sourcelocation]\wad\docproject

Once there, build docs by typing

make html

This runs the batch file make.bat and the html argument causes the docs to be built. The output html docs will be found in the folder \build\html relative to where you started, that is, in

[sourcelocation]\wad\docproject\build\html.

The other argument that can be used with make is clean, which will clean your docs out entirely so that a full build will occur next time make html is used.

clean is rarely needed. Successive uses of make html will work on changed documents only and such runs will take ~30 seconds. By contrast, a full build after clean will take 10 minutes.

“Where’s the Source?”

It’s in the source. Apologies for the tautology. Here is the trick:
    (1) start with the URL of the needed doc,
    (2) subtract [parent]/docproject/build/html from its path/URL,
    (3) replace “.html” at end with “.rst”.
This is where the file is.

  1. file:///C:/source/wad9/wad/docproject/build/html/common/docproject/utilities/icgsphinxhelp/icgsphinxhelp.html

  2. file:///C:/source/wad9/common/docproject/utilities/icgsphinxhelp/icgsphinxhelp.html

  3. C:\source\wad9\common\docproject\utilities\icgsphinxhelp\icgsphinxhelp.rst

[parent] is the folder containing the docproject folder from which make.bat was run. In the above that folder is wad.

Next

Player’s choice.

  • Jump in the deep end: find a document similar to the one that is to be created and copy it or use it as a guide. See how far it goes. This will work better than one would expect.

  • Be guided a bit: look at the “ICG Docs” section on the nav table above. This section goes through most of how things are done in the Itasca docs, including an anatomical breakdown of a command doc, a FISH doc, and an example doc, which are probably the most important ones for developers doing documentation.

  • Be a good citizen: before doing anything review the “don’ts” doc to avoid the most common mistakes or to break any bad habits that have already developed.

  • Be thorough: use the nav table above to go through everything. Only Dave P would do this. If you are still here reading this, you are probably Dave P. [1]

Endnote