Sphinx Documentation

Sphinx is a documentation generator. It takes plain text source files written in reStructuredText or Markdown and produces HTML, PDF, ePub, and other output formats. It was originally created for the Python documentation and has since become the standard tool for technical documentation across a wide range of projects.

This series is written in reStructuredText and built with Sphinx. Setting up Sphinx locally means you can preview the documentation as you write it, check for broken references, and build the full HTML site before publishing. The same setup works for any other Sphinx-based documentation project.

Installation

Sphinx and its extensions are Python packages. The correct approach on Kubuntu 24.04 is to use a virtual environment rather than installing into the system Python, which avoids conflicts with system packages and keeps the documentation environment isolated.

Install the Python virtual environment tools if not already present:

sudo apt install python3-venv python3-pip

Setting up the Roll Your Own Network project

Clone the roll.urown.net repository:

mkdir -p ~/Projects
cd ~/Projects
git clone https://github.com/alainwolf/roll.urown.net.git
cd roll.urown.net

Create a virtual environment and activate it:

python3 -m venv .venv
source .venv/bin/activate

Install the required packages from the project’s requirements file:

pip install -r requirements.txt

If a requirements.txt is not present, install the packages listed in the project README directly:

pip install --upgrade \
    sphinx \
    sphinx-rtd-theme \
    pygments-solarized-style \
    pygments-openssl \
    ansible-pygments \
    pygments-redis \
    sphinxnotes-strike \
    sphinx-last-updated-by-git \
    sphinx-rtd-dark-mode

Building the documentation

With the virtual environment active, build the HTML documentation:

make html

The output lands in _build/html/. Open the index in Brave to preview:

brave-browser _build/html/index.html

Or open the directory in Dolphin and double-click index.html.

To clean the build directory and rebuild from scratch:

make clean html

Live preview with sphinx-autobuild

sphinx-autobuild watches the source files for changes and rebuilds automatically, serving the result via a local web server. This is more practical than running make html manually after every change.

Install it in the virtual environment:

pip install sphinx-autobuild

Start the live preview server:

sphinx-autobuild . _build/html --open-browser

The browser opens automatically and refreshes whenever a source file is saved. Port 8000 is the default; if it is in use, pass --port 8001 or similar.

Starting a new Sphinx project

To create a new documentation project from scratch:

mkdir -p ~/Projects/my-docs
cd ~/Projects/my-docs
python3 -m venv .venv
source .venv/bin/activate
pip install sphinx sphinx-rtd-theme

sphinx-quickstart

The quickstart wizard asks for the project name, author, and a few configuration choices. Accept the defaults where unsure. The result is a working project structure:

my-docs/
├── conf.py          # Sphinx configuration
├── index.rst        # Root document (table of contents)
├── Makefile         # Build shortcuts
├── _build/          # Generated output (not committed)
├── _static/         # Static files (CSS, images)
└── _templates/      # Custom HTML templates

reStructuredText basics

The source material for this series is written in reStructuredText (RST). A brief reference for the most common constructs:

Headings

Headings are underlined with a non-alphanumeric character. The character used determines the level, and must be consistent throughout the project:

Title
=====

Section
-------

Subsection
~~~~~~~~~~

Code blocks

Install the package::

    sudo apt install package-name

Or with syntax highlighting:

.. code-block:: bash

    sudo apt install package-name

Links

`Link text <https://example.com>`_

Or a reference: `Link text`_

.. _Link text: https://example.com

Notes and warnings

.. note::

    This is a note box.

.. warning::

    This is a warning box.

Including other files

.. toctree::
   :maxdepth: 2

   introduction
   installation
   configuration

Markdown support

Sphinx supports Markdown via the myst-parser extension, which is useful if you prefer Markdown to reStructuredText. Install it in the virtual environment:

pip install myst-parser

Add it to conf.py:

extensions = [
    'myst_parser',
]

Once enabled, Sphinx processes both .rst and .md files. The two formats can coexist in the same project.

Activating the virtual environment

The virtual environment must be activated before running any Sphinx commands. Add a shell alias to make this convenient:

# Add to ~/.bashrc
alias docs-activate='source ~/Projects/roll.urown.net/.venv/bin/activate'
alias docs-build='cd ~/Projects/roll.urown.net && source .venv/bin/activate && make html'
alias docs-serve='cd ~/Projects/roll.urown.net && source .venv/bin/activate && sphinx-autobuild . _build/html --open-browser'

Reload the shell:

source ~/.bashrc

Running docs-serve from anywhere opens the live preview server for the project.

Checking for broken references

Sphinx can check all internal and external links in a documentation project:

make linkcheck

The output lists any broken or redirected links with their file and line number. Worth running periodically, particularly for a project that references external URLs.

The virtual environment directory (.venv) should be excluded from the Borg backup in borgmatic’s exclude patterns. It can always be recreated from requirements.txt and does not need to be backed up. Add **/.venv to the exclude list in ~/.config/borgmatic/user.yaml.