reStructuredText & Sphinx

Basics (docutils)

Extensions by Sphinx

Third-party extensions

Autodoc

  • sphinx-autodoc-typehints: Use type annotations for documenting acceptable argument types and return value types of function

  • sphinx-click: Automatically extract documentation from a Click-based application and include it in your docs

Code blocks & prompts

  • sphinx-copybutton: Adds a copy button to all code and command line blocks

  • sphinx-prompt: Directive for unselectable prompts (nice for bash sections)

Design Elements

Jupyter Notebooks

  • nbsphinx: Extension that provides a source parser for *.ipynb files

  • jupyter_sphinx: Directive to define Jupyter-like code cells, embedding its output

Git

  • sphinx-git: Directive for adding latest git commits information to docs

  • sphinx-gitstamp: Directive for inserting a git datestamp into the context

Graphs

Publish

  • sphinxcontrib-confluencebuilder: Sphinx extension to build Atlassian Confluence Storage Markup

  • sphinx-sitemap: Generate multi-version and multi-language sitemaps.org compliant sitemaps for the HTML version of your Sphinx documentation

Quoting

Substitution

Themes

Additional themes can be browsed in the Sphinx Themes Gallery.

Tweaks

Videos

Custom extensions

Plug-ins

  • unicode-guilabel: Support single unicode character (e.g. emoji) inside guilabel role.

    Usage Example:

    You can click the :unicode-guilabel:`ᐊ` and :unicode-guilabel:`ᐅ`
buttons to navigate.

    renders into

    You can click the ᐊ and ᐅ buttons to navigate.

    Hint

    You can get Unicode HTML Codes at https://symbl.cc/en/.

Directives

The following custom directives are available in this documentation:

Admonitions

.. admonition:: Design Principle
    :class: design_principle

    Functions should either be **queries** or **commands**. Queries are for getting
    data, but must not change the state. Commands are supposed to change the state,
    but must not return any data. Functions must not do both.

.. admonition:: Pattern Definition
    :class: pattern_definition

    The **Abstract Factory Pattern** provides an interface for creating families
    of related or dependent objects without specifying their concrete classes.

.. admonition:: Problem
    :class: problem

    Some content for the custom problem admonition which is not important here.

renders into

Design Principle

Functions should either be queries or commands. Queries are for getting data, but must not change the state. Commands are supposed to change the state, but must not return any data. Functions must not do both.

Pattern Definition

The Abstract Factory Pattern provides an interface for creating families of related or dependent objects without specifying their concrete classes.

Problem

Some content for the custom problem admonition which is not important here.

Roles

The following custom roles are available in this documentation:

Inline Code Highlighting

Syntax highlighting for inline code for various languages:

* **Python**: Use the command :python:`print "Hello World"` to say hi.
* **Java**: Use the command :java:`System.out.println("Hello World");` to say hi.
* **JavaScript**: Use command :javascript:`console.log("Hello World");` to say hi.
* **HTML**: Use line :html:`<p>Hello World</p>` to say hi.
* **RST**: Use line :rst:`**Hello World**` to boldly say hi.
* **Bash**: Use line :bash:`echo "Hello World"` to say hi.

renders into

  • Python: Use the command print "Hello World" to say hi.

  • Java: Use the command System.out.println("Hello World"); to say hi.

  • JavaScript: Use command console.log("Hello World"); to say hi.

  • HTML: Use line <p>Hello World</p> to say hi.

  • RST: Use line **Hello World** to boldly say hi.

  • Bash: Use line echo "Hello World" to say hi.

Raw HTML

Sometimes reStructureText does not offer a proper symbol or styling capabilities for a desired HTML output, in which case a raw HTML string can be used:

This is my phone number: :raw-html:`&#9742;` 0170-123456789.
This is called a :raw-html:`<span style="font-family: Courier">description</span>`.

renders into

This is my phone number: ☎ 0170-123456789.
This is called a description.

Colors

Background colors in :rbg:`red` and :gbg:`green`, as well as foreground color in
:rfg:`red` and :gfg:`green`.

renders into

Background colors in red and green, as well as foreground color in red and green.

Other formatting

:ulined:`Underlined` text parts

renders into

Underlined text parts

:strike:`Struck through` text parts

renders into

Struck through text parts