Cheat Sheet
- Authors:
- Created:
04/01/2020
- Modified:
09/19/2025
ReSTructured Text Snippets
Section Snippets
When writing reStructuredText, it is important to put the sections in the below order.
Sections:
#with overline, for parts*with overline, for chapters=, for sections-, for subsections^, for subsubsections", for paragraphs
Link Snippets
Internal Links
For linking within the same RST document WITHOUT using references, then do this::
My Section Title
=============================
Some content here.
...later in the same file ...
See `My Section Title`_
NOTE - This approach is brittle and breaks if either of the text changes. It also does NOT work across files.
BETTER WAY - For linking within the same RST document use references:
First, setup or find the reference to link to like this:
.. _my-special-section:
Then reference it like this:
:ref:`Custom Link Text about my section <my-special-section>`
External Links
For a direct URL link do something like this::
`External Documentation Page - Say Github <https:/github.com>`_
Reusable external link approach, you can use Sphinx’s extlinks extension::
.. extlink:: externaldocs
:prefix: https//extern-docs.example.com/
:name: External Docs
:externaldocs:`path/to/page.html`
Linking between Sphinx projects, use the sphinx.ext.intersphinx extension::
Add the necessary config to the conf.py after adding the extension to the conf.py:
intersphinx_mapping = {
'linux': ('https://writings.bradstancel.com/linux-docs', None),
'server-programs': ('https://writings.bradstancel.com/server-programs', None)
}
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
intersphinx_disabled_reftypes = ["*"]
Now you can reference it this way using “doc”::
:docs:`path/to/page`
For basic internal links, you can do this using “doc”::
:doc:`Custom Link Text <relative/path/to/another/rst/file/no/extension>`
For linking to a reference (specific section of a document), then do this::
:ref:`name-of-sphinx-reference`
or with custom text:
:ref:`This is my custom text <name-of-sphinx-reference>`
For linking to a reference in A SEPARATE Sphinx Documentation Project using Intersphinx do this::
:ref:`My Custom Link Text <my-intersphinx-config-entry:my-ref-from-other-project>`
for instance, if you were to have an entry in the intersphinx_mapping like shown above called server-programs and you wanted to link to a reference in THAT Sphinx project called aws-cli-version it would then look something like this:
:ref:`AWS CLI Info Link <server-programs:aws-cli-version>`
The key is that to make this reference, BOTH PROJECTS must use the Intersphinx extension
Common Snippets
To create a reference / shortcut / anchor link to a section do this::
.. _gnome-customizations:
To create and assign a value to a reference do this::
.. _Brad Stancel: https://bradstancel.com/
or
.. |date| date:: %m/%d/%Y
then use it like this:
:Authors: `Brad Stancel`_
:Created: 04/01/2020
:Modified: |date|
To make something downloadable do this::
:download:`Password Policy Screenshot 1 <images/Screenshot_2020-06-17_14.26.48-Annotated.png>`
Display an image do this::
.. image:: images/Screenshot_2020-06-17_14.26.48-Annotated.png
Show a Graphviz Diagram::
.. graphviz:: files/roles.dot
Show a PlantUML Diagram::
.. uml:: files/critical-path.uml
Show a Mermaid Diagram::
.. mermaid:: files/acm-flow-diagram.mermaid
To show a block of code or config do this::
.. code-block:: bash
sudo systemctl restart apache2.service
To reference a shortcut / anchor link like the one above do this (can be a different file in the project)::
:ref:`Whatever I want the link to say here <gnome-customizations>`
To do a literal include of a file do this::
.. include:: files/Entire-TCP-Conversation-of-Query-Between-OpsInsights-and-Client-Database.txt
:literal:
or something like this:
.. literalinclude:: files/php
:language: php
:linenos:
Reuse Content by Including a Shared File:
.. include:: ../shared/folder/filename.rst
Helpful if you are working on multiple projects, you can save entire topics in shared files, and include those files in multiple projects.
To show a CSV File::
.. csv-table:: Table Title
:file: CSV file path and name
:widths: 30, 70
:header-rows: 1
To show a block of SQL statements / code do this::
.. code-block:: sql
SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID;
To create a WARNING Message do this::
.. warning::
My Warning Message and Text goes here.
To create a NOTE Message do this::
.. note::
This is note text. Use a note for information you want the user to
pay particular attention to.
Use Conditional Text (Requires specifying something in Sphinx build/Makefile)::
.. only:: Internal
Content to be included only in the internal version of the document.
See this link for more details
Create a Glossary::
.. glossary::
Sphinx
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages.
Reference a Glossary Term using one of the below::
:term:`Sphinx`
or
:term:`reStructuredText<RST>`
See this link for more details
To embed a YouTube video do this::
.. youtube:: LSQNTZIPsvI
This requires the ``sphinxcontrib.youtube`` Sphinx extension to be installed
Sphinx Snippets
Some key things to do in the conf.py file are listed below.
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx_rtd_theme',
'sphinxcontrib.youtube',
'recommonmark',
'sphinx.ext.extlinks',
'sphinx.ext.graphviz',
'sphinx.ext.intersphinx',
'sphinxcontrib.plantuml',
'sphinxcontrib.mermaid',
'sphinx_copybutton'
]
project = 'Ops Insights SOC 2, Security and Compliance Documentation'
copyright = '2020, ProcessFast, LLC'
author = 'ProcessFast, LLC'
html_logo = '_static/_images/OpsInsights-Square-70x70.png'
html_favicon = '_static/_images/favicon.ico'
html_show_sourcelink = False