A Guide to reStructuredText for Structured Markup in Sphinx Documentation

reStructuredText (reST) serves as the default plaintext markup language for Sphinx documentation, facilitating structured and organized content creation. With its rich syntax, reST empowers developers to efficiently document their software projects. Let's delve into the key aspects of reStructuredText.

1. Paragraphs and Quoted Paragraphs

Paragraphs are blocks of text separated by blank lines. Quoted paragraphs are created by indenting them more than the surrounding paragraphs.

2. Inline Markup

- Single Asterisk: *text* for emphasis (italics).

- Double Asterisks: **text** for strong emphasis (bold).

- Backquotes: ``text`` for code samples.

Inline markup should not be nested, start or end with whitespace, or be surrounded by non-word characters.

3. Lists and Quote-link Blocks

- Asterisk at the start of a paragraph and proper indentation for bulleted lists.

- Numbered lists can be auto-numbered using a # sign.

- Nested lists must be separated from parent list items by blank lines.

- Definition lists and line blocks are supported.

4. Tables

reST supports simple tables, CSV tables, and list tables. Tables can be formatted using ASCII characters, making them easy to create and understand.

5. Hyperlinks

- External Links: `Link text <https://domain.invalid/>`_.

- Internal Links: Achieved via a reST role provided by Sphinx.

6. Sections

Section headers are created by underlining the section title with a punctuation character, defining the structure of the document.

7. Field Lists

Field lists are used for specifying field information in a structured format, commonly utilized in Python documentation.

8. Roles

Roles are inline markup pieces used to provide semantic markup and cross-referencing of identifiers. Sphinx supports various roles for different formatting purposes.

9. Explicit Markup

Explicit markup is used for constructs needing special handling, such as footnotes, highlighted paragraphs, comments, and generic directives.

10. Directives

- Directives are generic blocks of explicit markup.

- Used for various purposes, like admonitions, images, code blocks, containers, epigraphs, etc.

- Syntax involves the directive name, arguments, options, and content.

11. Images

reST supports the image directive for embedding images in documentation. Images can be auto-copied to the output directory when building with Sphinx.

12. Footnotes and Citations

Footnotes and citations are supported, aiding in providing additional information and references within the content.

13. Substitutions

Substitutions allow defining pieces of text or markup that can be referred to using a name, enhancing consistency and reusability.

14. Comments and Metadata

- Comments are treated as explicit markup blocks that aren't valid constructs.

- Metadata, such as HTML metadata and source encoding, can be defined using directives.

15. Source Encoding

reST assumes UTF-8 encoding by default, but you can change this with the source_encoding config value.

16. Gotchas

- Inline markup separation from surrounding text is important.

- No nested inline markup allowed.

In conclusion, reStructuredText is a versatile and powerful markup language tailored for Sphinx documentation. Its syntax enables developers to create well-organized, visually appealing, and easily navigable documentation for their projects. By leveraging reST's features, developers can communicate effectively and provide comprehensive guidance to users and stakeholders.

Raell Dottin