12.11. ReStructured Text for those who know Markdown

You can think of RST as “Markdown, but much better”. Meaning:

  1. RST is basically just as simple as Markdown

  2. But RST is both more precise, and has more available formatting constructs (without getting crazy complicated)

The full Sphinx / RST documentation is available here: https://www.sphinx-doc.org/en/master/index.html

If you’re familiar with Markdown, the following sections contain some tips to get you started in RST.

12.11.1. Whitespace and indenting

  • MD: Whitespace and indenting generally doesn’t matter in most cases. It does matter with bullets and sub bullets, but the rules get pretty weird, and vary between different Markdown renderers.

  • RST: Indenting matters. A lot. Just like Python. In general, you indent all RST text to keep it within the same level. For example, all this text would be a single paragraph

    Blank lines also matter. A lot. You use blank lines to delimit sections within an indenting level. For example, the blank line before this paragraph denotes a paragraph break.

    Note

    RST was created by the Python community. Hence, whitespace is quite important.

    • Indenting matters

    • Blank lines between content matter

Using a blank line and outdenting indicates the end of the previous item. For example, this paragraph is not part of the MD/RST bulleted list.

12.11.2. Fixed width font

  • MD: Use single quotes:

    `hello world`
    
  • RST: Use a pair of single quotes:

    ``hello world``
    

12.11.3. Italics

  • MD: *hello world* or _hello world_

  • RST: *hello world*

12.11.4. Boldface

  • MD: **hello world**

  • RST: Same as MD

12.11.5. Chapter and section delimiters

  • MD: Either use one or more pound signs (#, ##, ###) to the left of the line of text, or underline the line of text with pound signs

  • RST: Have a single line of text, underlined by non-ASCII characters.

    • The length of the underlying must be at least as long as the line of text

    • Which non-ASCII character is used for the underlying does not matter, but the order in which they are used denotes chapters / sections / subsections / etc.

      In these OMPI docs, the sequence of underline characters we use are:

      Chapter 1: hello world
      ======================
      
      Section 1: hello world
      ----------------------
      
      Subsection 1: hello world
      ^^^^^^^^^^^^^^^^^^^^^^^^^
      
      Subsubsection 1: hello world
      ++++++++++++++++++++++++++++
      

      Meaning: underlines made of = denotes chapters, underlines made of - denotes sections, underlines made of ^ denotes subsections, and underlines made of + denote subsubsections.

12.11.6. Multi-line code/fixed-width font

  • MD: Use three single quotes to delimit blocks of text. Optionally include a token keyword to denote the syntax highlighting to use inside that block.

    ```c
    int main() { printf("Hello world\n"); return 0 }
    ```
    
  • RST: Use .. code-block:: KEYWORD to start a section of code.

    .. code-block:: c
    
       int main() { printf("Hello world\n"); return 0 }
    
    • KEYWORD indicates which syntax highlighting to use (e.g., c, c++ make, sh, ini, Fortran, diff, python, java, rst, … etc.).

    • KEYWORD can be omitted if no specific highlighting is to be used.

    • There MUST be a blank line after the code-block line.

    • The lines in the block must be indented to the same column as the first c in code-block. For example:

      .. code-block:: sh
      
         shell$ tar xf openmpi-<version>.tar.bz2
         shell$ cd openmpi-<version>
         shell$ ./configure --prefix=<path> |& tee config.out
      

      Note that the code block will be rendered at the same level as where the first . of .. code-block:: starts. In this case, the example code block will be rendered in the bulleted item.

Whereas this parargraph and code block will be outside of the above bulleted list:

shell$ tar xf openmpi-<version>.tar.bz2
shell$ cd openmpi-<version>
shell$ ./configure --prefix=<path> |& tee config.out

# Fun note: the code-block can contain blank lines.

The code-block is terminated by a blank line and then outdent back to the same level as the first . in .. code-block::.

12.11.7. Un-numbered bullets

  • MD: Start lines with * or -

  • RST: Start lines with *. You can wrap lines at the same indenting level to make paragraphs in the same bullet.

    Having a blank line and then more text at the same indenting level makes another paragraph in the same bullet. You even put other directives in this same indenting level.

    • For example, you can start a sub bullet.

      This text is the next paragraph in the same sub bullet.

      This is a verbatim code block within this same sub bullet.
      More about code-blocks below.
      

      This is the next paragraph (after the code block) in the same sub bullet.

    • If you start a new bullet, that terminates the previous bullet.

    • You MUST put blank lines between bullets!

12.11.8. Numbered bullets:

  • MD: Start lines with #

  • RST: Start lines with #.

    Important

    Yes, the trailing . is important

    For example:

    #. Item number 1
    #. The second item
    #. A third item
    

    All the same rules for indentation apply as described above.

12.11.9. Comments

  • MD: Enclose content in <!-- and --> (i.e., HTML comments, but they are included in the output)

  • RST: Start a line with two periods and a space.

    For example, the following block is a comment, and will not be included in the output:

    .. Hello world.  This is a comment.  This whole block is a
       comment.  You can leave it here in the final document, and it
       will not be included in the rendered output.
    
       Your comment can even include blank lines.  You terminate a
       comment -- just like most other things in RST -- by a blank
       line and then outdenting back out to the same column as the
       first ".".
    
    This line is no longer part of the comment.
    

12.11.10. Including files

  • MD: You cannot include files in Markdown.

  • RST: Use the .. include:: FILENAME directive. For example:

    .. include:: features-extensions.rst
    .. include:: features-java.rst
    

    Those directives include those 2 files right here in this RST file.

    Important

    Chapter/section/subsection delimiters will be continued in those files as part of rendering this file.

12.11.14. Macros

  • MD: There are no macros in Markdown.

  • RST: We have defined a few OMPI-specific macros in RST. You can insert these macros anywhere in RST content text.

    • |ompi_ver| is the full Open MPI version number, including alpha/beta/rc/greek denotation. For example 5.0.0rc1.

    • |ompi_series| is the major/minor Open MPI version, e.g., 5.0.x.

      Important

      Think twice about hard-coding the Open MPI version number or series when referring to the current version or series. It can be appropriate to hard-code an “x.y.0” version to denote a generational epoch, but in most other cases, you probably want to use one of the macros.

    • |mdash| is a unicode long dash, an “em” dash. Use it instead of --.

    • |rarrow| is a unicode right arrow. Use it instead of -> or -->.

12.11.15. Brightly-colored boxes

  • MD: There are no brightly-colored boxes in MD.

  • RST: You can use various directives to make brightly-colored “note” boxes (Called admonitions) in RST. For example:

    Important

    a green box with a “!” icon

    Standard indenting rules apply for the content in the box. You can have multiple lines and multiple paragraphs, for example.

    Yippee.

    • You can even have bullets.

      You can even have code blocks inside the bullet inside the
      caution box.
      
    • All the standard indenting rules apply.

    Hint

    a green box with a “!” icon

    Note

    a blue box with a “!” icon

    Caution

    an orange box with a “!” icon

    Attention

    an orange box with a “!” icon

    Warning

    an orange box with a “!” icon

    Error

    a red box with a “!” icon

    Danger

    a red box with a “!” icon

    Custom title

    You can name this box whatever you want:

    .. admonition:: Custom title
       :class: tip
    
       Content of your box here.
    

    Custom text for this custom admonition. Note that the :class: <type> will change the coloring to the color for the basic admonition of that type. E.g., :class: tip makes the box be green.