Use Sphinx to Create Documentation in Multiple Formats on AlmaLinux 9
Install Sphinx in a virtual environment on AlmaLinux 9 or Rocky Linux 9, write pages in reStructuredText or Markdown, and build HTML, EPUB and PDF output.
Sphinx reads plain-text source files written in reStructuredText or Markdown and builds them into a linked HTML site, an EPUB book, manual pages, plain text or a PDF. This guide installs the current Sphinx release in a Python virtual environment on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, creates a small project and builds it in several formats. CentOS 7 reached end of life on 30 June 2024, so use one of these releases instead. Apart from the package manager commands, every step is the same on Debian and Ubuntu.
Requirements
- A server or workstation running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9.
- A regular user with
sudorights (the examples usedeploy). - A recent Python. Sphinx drops old interpreters quickly: the 9.1 series needs Python 3.12 or newer, and 9.2, released in October 2026, needs Python 3.13 or newer. The system Python on the RHEL 9 family is 3.9, which is too old for any current Sphinx release.
The fix is to install the newer Python 3.12 package that the distribution provides next to the system interpreter and build a virtual environment from it. pip then selects the newest Sphinx release that supports that interpreter. Do not run sudo pip install: it writes into system directories that dnf manages.
Step 1: Install Python 3.12 and make
Update the system and install the interpreter and make, which runs the build targets Sphinx generates:
sudo dnf update -y
sudo dnf install -y python3.12 makeConfirm the version:
python3.12 --versionStep 2: Create a project directory and virtual environment
Keep each documentation project in its own directory with its own environment:
mkdir -p ~/docs/handbook
cd ~/docs/handbook
python3.12 -m venv .venv
source .venv/bin/activateYour prompt now starts with (.venv). Install Sphinx inside the environment and check what you got:
python -m pip install --upgrade pip
python -m pip install -U sphinx
sphinx-build --versionRun source ~/docs/handbook/.venv/bin/activate again whenever you open a new shell to work on the project.
Step 3: Generate the project skeleton
sphinx-quickstart asks a few questions (whether to separate source and build directories, project name, author, release, language) and writes a working configuration:
sphinx-quickstartAccept the default of not separating the directories for a small project. To skip the questions, pass the answers as options; -q requires -p, -a and -v:
sphinx-quickstart -q -p "Server Handbook" -a "Deploy Team" -v 1.0The directory now contains:
| Path | Purpose |
|---|---|
conf.py | Project configuration: name, extensions, theme |
index.rst | Root document with the table of contents tree |
Makefile, make.bat | Shortcuts for sphinx-build on Linux and Windows |
_build/ | Generated output, one sub-directory per format |
_static/ | Your own stylesheets and images |
_templates/ | Custom page templates |
Step 4: Write pages and add them to the toctree
Each page is a separate .rst file. Create a first one:
cat > introduction.rst <<'EOF'
Introduction
============
This handbook describes how the **example.com** servers are set up.
Conventions
-----------
* Commands are run as the ``deploy`` user.
* Server addresses use the ``203.0.113.0/24`` range.
.. code-block:: bash
ssh deploy@203.0.113.10
EOFCreate a second page the same way:
cat > installation.rst <<'EOF'
Installation
============
.. note::
Take a snapshot before you change a production server.
#. Update the system.
#. Install the packages.
#. Verify the service.
EOFPages only appear in the output when the root document references them. Open index.rst and list the file names under the toctree directive:
.. toctree::
:maxdepth: 2
:caption: Contents:
introduction
installationThe rules that trip people up are all about whitespace: leave one blank line between the options and the list, indent the entries to line up with :maxdepth:, write one document per line in reading order, and leave off the .rst extension. Documents in sub-directories are written as relative paths such as usage/backup.
Step 5: Build the HTML version
make htmlThe site is written to _build/html/, with index.html as the start page. make html is a shortcut for sphinx-build -M html . _build. Sphinx prints a warning for every page that is not in a toctree and for every broken reference, so read the build output.
To look at the result from your own computer without publishing it, serve the directory on the loopback interface and forward the port over SSH:
python -m http.server 8000 --bind 127.0.0.1 --directory _build/htmlOn your computer run ssh -L 8000:127.0.0.1:8000 deploy@203.0.113.10 and open http://127.0.0.1:8000/. To publish, copy the contents of _build/html/ to the document root of any web server; the output is static files.
Step 6: Build other formats
The same sources feed every builder. Run make with the builder name:
| Command | Result |
|---|---|
make html | One HTML page per document |
make dirhtml | HTML with one directory per page, for clean URLs |
make singlehtml | The whole project as a single HTML file |
make epub | An EPUB 3 e-book in _build/epub/ |
make man | groff manual pages |
make text | Plain text files |
make latexpdf | LaTeX sources compiled to PDF in _build/latex/ |
make linkcheck | No output format: checks every external link |
Run make clean to delete everything under _build/ before a full rebuild.
Step 7: Build a PDF
The PDF route goes through LaTeX, so make latexpdf needs a TeX Live installation and latexmk in addition to Sphinx. The Sphinx documentation lists the required packages for Debian and Ubuntu:
sudo apt install -y texlive-latex-recommended texlive-fonts-recommended texlive-fonts-extra tex-gyre texlive-latex-extra latexmkIt gives no equivalent list for the RHEL family. On AlmaLinux 9 and Rocky Linux 9 the dependable route is the container image the Sphinx project publishes for this purpose, sphinxdoc/sphinx-latexpdf, which already contains TeX Live. Install Podman and run the build inside the image from your project directory:
sudo dnf install -y podman
cd ~/docs/handbook
podman run --rm -v "$PWD":/docs:Z docker.io/sphinxdoc/sphinx-latexpdf make latexpdfThe image is larger than 2 GB, so the first run takes a while. The :Z suffix relabels the directory so SELinux lets the container write to it. The finished PDF is in _build/latex/. The container uses the Sphinx inside the image, not your virtual environment, so a project that needs extra extensions or a third-party theme needs an image of its own, built from this one with those packages added.
Writing in Markdown
Sphinx reads Markdown through the MyST-Parser extension. Install it in the virtual environment:
python -m pip install --upgrade myst-parserThen enable it in conf.py:
extensions = ['myst_parser']Files ending in .md are now parsed as Markdown and can be listed in the toctree next to .rst files.
Keeping builds reproducible
Record the exact versions in the project so another machine, or the same machine next year, builds the same output:
python -m pip freeze > requirements.txtRecreate the environment anywhere with python3.12 -m venv .venv, activate it and run python -m pip install -r requirements.txt. Commit conf.py, the source files and requirements.txt to version control, and leave _build/ and .venv/ out.
Frequently asked questions
Why not install Sphinx with dnf?
Distribution packages of Sphinx are tied to the system Python and stay at the version that was current when the distribution was released. Themes and extensions from PyPI often need a newer Sphinx than that, and mixing dnf and pip packages in the same interpreter causes conflicts. A virtual environment keeps the project independent of the operating system.
How do I change how the HTML looks?
Set html_theme in conf.py. Sphinx ships a handful of built-in themes and uses alabaster by default; third-party themes such as furo are installed with pip into the same environment and then named in html_theme. Put your own CSS in _static/.
Can Sphinx document Python code automatically?
Yes. The bundled sphinx.ext.autodoc extension pulls docstrings from importable modules. Add it to the extensions list in conf.py, or pass --ext-autodoc to sphinx-quickstart when you create the project. The code must be importable from the environment Sphinx runs in.
Do I need Sphinx on the web server that hosts the documentation?
No. The HTML output is a directory of static files. Build it anywhere, including a CI job, and copy _build/html/ to the server.