Basic Documentation with Sphinx

Start a Sphinx project

  1. Create virtual environment

  2. Install Sphinx

  3. Setup documentation project

  4. Build documentation

1. Create virtual environment

This step is optional. You can use Python installed on your system directly. However it is good practice to keep your project isolated from other projects. This could be achieved with Python virtual environment.

$ py -3.10 -m venv .venv310

Above command will create a directory .venv310 with local “copy” of Python 3.10 - a virtual environment. To use the virtual environment you need to activate it.

To activate Python virtual environment in bash:

$ source .venv310/Scripts/activate
(.venv310)
$

To activate Python virtual environment in PowerShell:

PS> .\.venv310\Scripts\Activate.ps1
(.venv310) PS>

To activate Python virtual environment in Windows Command Prompt:

C:\myproj> .venv310\Scripts\activate.bat
(.venv310) C:\myproj>

Virtual environment is active only for the console session it has been activated for. All packages you install are installed into the virtual environment and do not have any impact on the global Python environment.

2. Install Sphinx

You can use pip to install sphinx package directly. I personally prefer to use requirements.txt file:

# FILE: -- requirements.txt
sphinx
sphinx-rtd-theme

Than run pip to install required packages:

$ pip install --upgrade -r requirements.txt
...

3. Setup Sphinx project

Document sources need to be stored in a directory. Common approach is to use docs directory under the project root to keep the documentation sources and artifacts. To initialize the directory as Sphinx project, the sphinx-quickstart is used:

$ mkdir docs
$ cd docs
$ sphinx-quickstart

Modify the index.rst file created by sphinx-quickstart - delete last section:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Optionally update the conf.py file to change the default theme:

Replace

html_theme = 'alabaster'

with

html_theme = 'sphinx_rtd_theme'

RTD_NEW_THEME = True

html_theme_options = {
    'display_version': False,
}

html_show_sphinx = False

If you want to experiment with other themes, you can look at:

4. Build documentation

To build the documentation from the docs directory you execute the make script. make script supports various output formats. To build documentation in HTML format:

$ make html
Running Sphinx v4.3.1
loading pickled environment... done
...................................
dumping object inventory... done
build succeeded.

The HTML pages are in _build\html.

You can build other formats, e.g.

  • epub

  • latex

  • text

  • gettext

  • singlehtml

  • dirhtml

For more information on Sphinx build refer to the documentation.

Hosting on Read the Docs

Add build requirements

If you need to install additional build-time dependencies, e.g. for a custom theme, you can create a .readthedocs.yaml file and place it at the root of your project:

version: 2

python:
  install:
    - requirements: requirements.txt

If necessary, you coul have more than one requirements.txt file and specify Python version to be used:

version: 2

python:
  version: "3.7"
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt

For more information refer to Configuration File V2 documentation.

Further reading