11.11. ReStructured Text for those who know Markdown
You can think of RST as “Markdown, but much better”. Meaning:
- RST is basically just as simple as Markdown 
- 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.
11.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.
11.11.2. Fixed width font
- MD: Use single quotes: - `hello world`
- RST: Use a pair of single quotes: - ``hello world``
11.11.3. Italics
- MD: - *hello world*or- _hello world_
- RST: - *hello world*
11.11.4. Boldface
- MD: - **hello world**
- RST: Same as MD 
11.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 OpenPMIx 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.
 
11.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:: KEYWORDto 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-blockline.
- The lines in the block must be indented to the same column as the first - cin- code-block. For example:- .. code-block:: sh shell$ tar xf pmix-<version>.tar.bz2 shell$ cd pmix-<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 pmix-<version>.tar.bz2
shell$ cd pmix-<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::.
11.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! 
 
11.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. 
11.11.10. Including files
- MD: You cannot include files in Markdown. 
- RST: Use the - .. include:: FILENAMEdirective. 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. 
11.11.11. Hyperlinks to URLs
- MD: - [this is the link text](https://example.com/) 
- RST: - `this is the link text <https://example.com/>`_ - Important - Yes, the trailing underscore in RST is important. It’s a little weird, but you’ll cope. 
11.11.12. Hyperlinks to anchors
- MD: I forget offhand how to make anchors and links to them in MD. 
- RST: Use the - :ref:directive.- Make an anchor like this: - .. _ANCHOR_NAME: - It must start with and underscore and end with a colon. - I’ve typically used anchor names that either begin with - label-or end in- -labelto make it blatantly obvious that it’s a label. For example:- .. _building-and-installing-section-label: - Then you can use the - :ref:directive:- be sure to see :ref:`the VPATH build section <building-and-installing-section-label>`.
11.11.13. Hyperlinks to other (RST) pages
- MD: - [link text](page_name) 
- RST: Use the - :doc:directive.- General format: - :doc:`link text <PAGE_PATH>` - For example: - You should read :doc:`the Developer's Guide </developers>`. - The page path is relative to the - docsdir in the OpenPMIx git tree.
11.11.14. Macros
- MD: There are no macros in Markdown. 
- RST: We have defined a few OpenPMIx-specific macros in RST. You can insert these macros anywhere in RST content text. - |ompi_ver|is the full OpenPMIx version number, including alpha/beta/rc/greek denotation. For example- 5.0.0rc1.
- |ompi_series|is the major/minor OpenPMIx version, e.g.,- 5.0.x.- Important - Think twice about hard-coding the OpenPMIx 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- -->.
 
11.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: tipmakes the box be green.
11.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: