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:
- 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:
See also
- 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.)
- Internal link – to a section title
You can place a label before a section title using :ref:`label-name`. The section you are cross-referencing can be in the same file, a different file, or even a different document within the MDAO user documentation. However, label names must be unique.
For example, if you are in the Developer’s Guide and want to refer the user to the tutorial problem overview in the User’s Guide, you would type something like the following in the source file:
Please see the tutorial problem, specifically the :ref:`Problem-Overview`.
In the User’s Guide you would place the label before the section title, as follows:
.. _Problem-Overview:
Problem Overview
----------------
The overall objective of the tutorial problem is to design . . . .
Note the hyphenation between words in the label and the cross reference to the label.
You can use same type of cross-reference label with figures. See Figures.
- Internal links – to an arbitrary location
Labels that aren’t placed before a section title can still be referenced, but you must give the link an explicit title using this syntax: :ref:`Link title <label-name>`. For example, the cross reference :ref:`process model <process-model>` appears in the HTML text file as:
process model
The label below was placed above the paragraph in the User Guide that discusses the process model and shows a figure of it,
.. _`process-model`:
So, clicking on th cross reference in the text file takes you to where the label was placed. In this case an arbitrary label was created rather than cross referencing to the figure title.
- Seealso directive
This directive is similar to the internal link to a section title that was previously described. However, when you use this directive, the text (cross reference) appears in a highlighted box that spans the width of the page.
For example, typing this:
.. seealso:: :ref:`Bazaar-Commands`
results in:
See also
You must also place a label before the section referred to, for example:
.. _Bazaar-Commands:
- External link – to a specific web address
Use `Link text <http://target>`_ for inline web links.
If the link text should be the Web address, you don’t need special markup; just type the address in the reST file, and the parser will find the link/mailing address in the text.
- External link – to more than one web address (anonymous hyperlink)
On occasion you may want to use identical text as the hyperlink to different web addresses. In such a case, you must create anonymous hyperlinks. No text label precedes the web address; however, a double underscore is required after the text link (i.e., `reStructuredTest`__ in the example that follows) and before the web address (e.g., .. __: http://docutils.sourceforge.net/rst.html).
This is an example where reStructuredText acts as the hyperlink to two different web addresses.
You type this:
`reStructuredText`__
.. __: http://docutils.sourceforge.net/docs/user/rst/quickstart.html
to go to the reStructuredText Primer:
And you type the same link text but a slightly different web address:
`reStructuredText`__
.. __: http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt
to take you to the reStructuredText Cheat Sheet:
- 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
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.
To create a list:
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:
- 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):
In either case, you get this:
- 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.
- Simple table:
The following table is an example of simple table. When you create a simple table, you must:
================== =========================================== =======
**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:
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. |
|
|
body row 4 |
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.
will appear in the index under the P’s as:
Python
module
and under the M’s as:
module
Python
will appear under the P’s as:
plugins,
registering
- Shortcut for single entries
.. index:: component, assembly, egg, plugins
For details on testing code in the documentation, please refer to Testing Code in the Documentation in the Developer’s Guide.
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.