Sphinx and reStructuredText

OpenMDAO uses reStructuredText (reST), a plaintext markup language that is part of the Docutils text-processing system, to create documentation files. Sphinx is a Python documentation generator that converts reST to HTML. While reST provides the basic structure (Docutils is the parsing and translating suite), Sphinx has specific directives that are used with reST to produce the desired results. For more information, please see the references that follow.

References:

Some Basics

  • The reST markup language assumes that a paragraph is the space between two blank lines. One blank line between paragraphs is treated the same as four blank lines between paragraphs.
  • You need at least one space between words and after periods. Extra spaces are ignored.
  • Use one asterisk for emphasis (italics): *italics*
  • Use two asterisks for strong emphasis (boldface) **boldface**
  • When numbering items (such as steps in a task or process), DO NOT indent the numbers – put them flush left. When numbers are indented, they do not display correctly in Internet Explorer (although they look fine in Firefox and Safari). If the numbered item is long and you wrap it, it could also cause display issues in IE.
  • All text in headings (level one, level two, level three, etc.) must be underlined. (In OpenMDAO documents, generally the title is overlined and underlined, while the other headings are underlined only. All levels must be different. Please see the Style Guide for more information.)
  • If you get a Sphinx build error that says “Unexpected indentation,” it is probably because Sphinx is expecting a blank line, such as after a literal text block. Your line may have wrapped and confused Sphinx. In this case, try pulling the text up to the previous line even if it extends out past the margin of your window. Or, you could press Enter to go to the next line, but be sure to indent the text on the new line.

Literal Text

- Inline literal text:

Use this markup for code samples or or any time you want literal text.

Typing this:

``Inline literal text``

will result in this:

Inline literal text

- Literal code block:

To introduce a literal code block, use a double colon and skip a line before the text. Also, you must indent at least two spaces. For example, typing this:

::

  self.connect('velocity', 'chassis.velocity')
  self.connect('velocity', 'transmission.velocity')
  self.connect('tire_circumference', 'chassis.tire_circ')
  self.connect('tire_circumference', 'transmission.tire_circ')

will produce this:

self.connect('velocity', 'chassis.velocity')
self.connect('velocity', 'transmission.velocity')
self.connect('tire_circumference', 'chassis.tire_circ')
self.connect('tire_circumference', 'transmission.tire_circ')

Syntax highlighting is done automatically for Python code if Pygments (a Python syntax highlighter) is installed.

Note

You can also use this special marker (::) to introduce non-code literal text for use in examples. (It was used to show the index examples and other example files in this section.)

Figures

- Generated figures

In the OpenMDAO documentation, we have been using the open source Dia application to create diagrams (figures) and saving them as .png files. (A script automatically resizes the Dia files for our documentation.) Since these files may need to be updated, they go in the docs/generated_images directory on your branch.

Here is an example of how to link to a figure:

.. _`Class Diagram of Core Classes`:

.. figure:: ../generated_images/ModelClasses.png
   :align: center

   Class Diagram of Core Classes

In the above example, .. _`Class Diagram of Core Classes`: is an optional label that is used for cross referencing to this figure. In this case there was some preceding text: The figure `Class Diagram of Core Classes`_ shows . . . . A cross reference is not necessary, but if you are discussing a figure that appears later in the text, it is helpful to the reader.

The path to the image is: .. figure:: ../generated_images/ModelClasses.png. Generally we align our figures center, as shown in the example, but that is up to the author.

Last is the figure caption: Class Diagram of Core Classes. You must leave a blank line before the caption. You would also leave a blank line after it, since it is the end of a paragraph. (In Firefox, figure captions are automatically centered, but in Internet Explorer they appear flush left.)

- Static figures

Static figures are stored in docs/images/<document_directory> on your branch. Here is an example from the User Guide where the author pulled in a static figure titled EPA City Driving Profile.

.. figure:: ../images/user-guide/EPA-city.gif
   :align: center

   EPA City Driving Profile

Adding Extra Lines/Maintaining Line Breaks

If you want to add an extra line after a graphic or table, use the vertical bar (“|”) found above the backslash on the keyboard. Put it on a line by itself.

Also use the vertical bar when you want to maintain line breaks. You might want to do this inside a specific block of text. If your text needs to be indented, then first indent, type the vertical bar, leave a space, and then type the desired text.

Lists/Bullets

To create a list:

  • Place an asterisk (or hyphen or plus sign) at the start of a paragraph (list item).
  • Indent any line after the first line in a list item so it aligns with the first line. The same goes for numbered lists.
  • Leave a blank line after the last list item.

You may insert a blank line between list items, but it is not necessary and does not change how they appear.

- Bullet list:

Typing this:

* Determine acceleration required to reach next velocity point
* Determine correct gear
* Solve for throttle position that matches the required
  acceleration

will result in this:

  • Determine acceleration required to reach next velocity point
  • Determine correct gear
  • Solve for throttle position that matches the required acceleration

- Numbered list:

You can type this:

1. Torque seen by the transmission
2. Fuel burn under current load

or this (using a # sign to auto number the items):

#. Torque seen by the transmission
#. Fuel burn under current load

In either case, you get this:

  1. Torque seen by the transmission
  2. Fuel burn under current load

- Nested list:

To create a nested list, you must place a blank line between the parent list and the nested list and indent the nested list.

* Item 1 in the parent list
* Subitems in the parent list

  * Beginning of a nested list
  * Subitems in nested list

* Parent list continues

In this case, it results in this:

  • Item 1 in the parent list

  • Subitems in the parent list

    • Beginning of a nested list
    • Subitems in nested list
  • Parent list continues

You may notice that even though we didn’t put a blank line between items in the parent list, a blank line appears between them because of our nested list. Whenever there is nested bullet list or a bullet is longer than one paragraph, a blank line appears between bullet items. Otherwise, there is no blank line between bullet items. Consequently, different sets of bullets within the same document will look different (inconsistent). This is the way reST or Sphinx currently works, and the author cannot change it.

Tables

- Simple table:

The following table is an example of simple table. When you create a simple table, you must:

  • Leave at least 2 spaces between columns
  • Make sure the space between columns is free of text
  • Make sure the overline and underlines are all of identical length
==================  ===========================================  =======
**Variable**        **Description**                              **Units**
------------------  -------------------------------------------  -------
power               Power produced by engine                     kW
------------------  -------------------------------------------  -------
torque              Torque produced by engine                    N*m
------------------  -------------------------------------------  -------
fuel_burn           Fuel burn rate                               li/sec
------------------  -------------------------------------------  -------
engine_weight       Engine weight estimate                       kg
==================  ===========================================  =======

it results in:

Variable Description Units
power Power produced by engine kW
torque Torque produced by engine N*m
fuel_burn Fuel burn rate li/sec
engine_weight Engine weight estimate kg

The table that is generated does not have a box outline around it. Also, there is no space after the column line. Indenting the text does not affect this; the text will still be flush left to the column. (We can only hope that at some future date, the appearance of tables will be improved.)

- Grid table:

Grid tables are more cumbersome to produce because they require lines between columns and rows, and at the intersections of columns and rows. Use a simple table unless you have cell content or row and column spans that cannot be displayed using a simple table.

The grid table uses these characters:

  • Equals sign (“=”) to separate an optional header row from the table body
  • Vertical bar (“|”) to create column separators
  • Hyphen (“-“) to create row separators
  • Plus sign (“+”) for the intersections of rows and columns

Typing this:

+------------------------+------------+-----------+----------+
| Header row, column 1   | Header 2   | Header 3  | Header 4 |
| (header rows optional) |            |           |          |
+========================+============+===========+==========+
| body row 1, column 1   | column 2   | column 3  | column 4 |
+------------------------+------------+-----------+----------+
| body row 2             |Cells may span columns, if desired.|
+------------------------+------------+----------------------+
| body row 3             | Cells could| - Table cells        |
+------------------------+ also span  | - contain            |
| body row 4             | rows, as   | - body elements.     |
|                        | shown in   |                      |
|                        | this       |                      |
|                        | example.   |                      |
+------------------------+------------+----------------------+

will produce this:

Header row, column 1 (header rows optional) Header 2 Header 3 Header 4
body row 1, column 1 column 2 column 3 column 4
body row 2 Cells may span columns, if desired.
body row 3 Cells could also span rows, as shown in this example.
  • Table cells
  • contain
  • body elements.
body row 4

Index Items

If you wish to add index items to a file as you are writing, please do. Additionally the tech writer will review new documentation and add index (and glossary) entries as needed. Index entries should precede the section or paragraph containing the text to be indexed. Note that all index entries are placed flush left. Some examples follow.

- Single term
.. index:: egg
Will appear in the index as:
egg
- Pair
.. index:: pair: Python; module

will appear in the index under the P’s as:

Python
    module

and under the M’s as:

module
    Python
- Modified single
.. plugins; registering

will appear under the P’s as:

plugins,
   registering

- Shortcut for single entries

.. index:: component, assembly, egg, plugins

Testing Code

For details on testing code in the documentation, please refer to Testing Code in the Documentation in the Developer’s Guide.

Including Code from the Source

See Including Code Straight from the Source in the Developer’s Guide.

Note

Whenever you include a code snippet, list, a block of text, or similar syntax, be sure to leave a blank line after the text. You might even need to extend the last line so it doesn’t wrap. This should avoid a Sphinx “Unexpected Indentation” error.