SPHINX - Documentation generation

Introduction

High-quality documentation is not just an add‑on, but the foundation of a successful project. It helps new users understand the API, speeds up development, and eases maintenance. Sphinx – documentation generation – is a powerful tool that automates the creation and building of documentation from Python source code.

Sphinx is used for the official documentation of Python, NumPy, Django, and many other large projects. It supports both manual writing and automatic generation of documentation from docstrings, making it a versatile solution for documenting code of any complexity.

What Is Sphinx and Why It Matters

Sphinx is a documentation generator written in Python that transforms source code and text files into beautiful, structured documentation in various formats. Its main advantage lies in its ability to automatically extract documentation from Python docstrings, allowing documentation to stay in sync with the code.

Main Advantages of Sphinx

Sphinx offers many features that make it the preferred choice for documentation:

• Automatic generation from Python docstrings
• Multiple output formats: HTML, PDF, ePub, LaTeX
• Extensibility through a plugin system
• Integration with version control systems and CI/CD
• Cross‑platform and easy to use

Installation and Initial Setup

Installing Sphinx

To start working with Sphinx, install the core package:

pip install sphinx

For extended functionality, it is also recommended to install additional packages:

pip install sphinx sphinx-rtd-theme myst-parser

Initializing Documentation

Creating the basic documentation project structure is done with the command:

sphinx-quickstart

The interactive wizard will ask you to choose:

• Project name and author
• Project version
• Documentation language
• Location of source files
• Documentation format (reStructuredText by default)

After finishing the setup, the following structure will be created:

docs/
├── _build/          # Built documentation
├── _static/         # Static files (CSS, JS, images)
├── _templates/      # Templates for customization
├── conf.py         # Configuration file
├── index.rst       # Main page
└── Makefile        # Build script

Documentation Project Structure

Core Components

conf.py – the central configuration file that controls all aspects of documentation generation. Here you set extensions, themes, paths to source code, and many other parameters.

index.rst – the root documentation file that serves as the table of contents and entry point for navigation throughout the docs.

_build/ – the directory where the finished documentation in various formats (HTML, PDF, ePub, etc.) is stored.

_static/ and _templates/ – folders for custom CSS, JavaScript files, and HTML templates for customizing the look of the documentation.

conf.py Configuration

Key configuration parameters include:

# Basic project information
project = 'My Project'
author = 'Author Name'
version = '1.0'
release = '1.0.0'

# Extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx',
]

# Theme
html_theme = 'sphinx_rtd_theme'

# Paths to source code
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

Automatic Documentation of Python Code

Enabling the autodoc Extension

To automatically generate documentation from docstrings, enable the appropriate extensions:

# In conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]

Configuring Paths to Modules

Add the path to your Python modules in conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

Automatic API Documentation Generation

To create documentation files for all modules, use:

sphinx-apidoc -o source/ ../src/

This command creates .rst files for all discovered Python modules and classes.

autodoc Settings

Additional options for fine‑tuning autodoc:

# Automatic documentation of class members
autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Working with reStructuredText (reST)

Basic Syntax

reStructuredText is the primary markup format for Sphinx. Core syntax elements:

Заголовок первого уровня
========================

Заголовок второго уровня
------------------------

Заголовок третьего уровня
~~~~~~~~~~~~~~~~~~~~~~~~~

**Bold text**, *italic*, ''monospace''

Lists:

* List item
* Another item

1. Numbered list
2. Second item

Links:

'External link <https://example.com>'_

:doc:'Internal link <another_document>'

Code blocks:

.. code-block:: python

    def hello():
        print("Hello, World!")

Sphinx Directives

Sphinx extends reStructuredText with special directives:

.. automodule:: mymodule
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: MyClass
   :members:
   :inherited-members:

.. autofunction:: my_function

.. note::
   This is an important note.

.. warning::
   This is a warning.

.. seealso::
   See also these sections.

Integration with Markdown and MyST

Installing Markdown Support

To work with Markdown files, install MyST‑parser:

pip install myst-parser

Configuration in conf.py

extensions = ['myst_parser']

# Support for multiple source formats
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

# MyST settings
myst_enable_extensions = [
    "deflist",
    "tasklist",
    "html_admonition",
    "html_image",
]

MyST Capabilities

MyST allows using extended Markdown syntax with full Sphinx directive support:

# Header

'''{note}
Note in Markdown
'''

'''{code-block}
def example():
    return "Hello"
'''

'''{autofunction}
'''

## Themes and Customization

### Popular Themes

**Read the Docs Theme** — the most popular theme:

'''bash
pip install sphinx_rtd_theme
'''

'''python
html_theme = 'sphinx_rtd_theme'
'''

Furo — a modern, minimalistic theme:

'''bash
pip install furo
'''

'''python
html_theme = 'furo'
'''

Theme Configuration

Most themes support customization via variables:

html_theme_options = {
    'navigation_depth': 4,
    'collapse_navigation': False,
    'sticky_navigation': True,
    'includehidden': True,
    'titles_only': False,
    'logo_only': False,
    'display_version': True,
}

# Custom CSS and JavaScript
html_static_path = ['_static']
html_css_files = ['custom.css']
html_js_files = ['custom.js']

Creating Custom Styles

Create the file _static/custom.css:

/* Custom styles */
.wy-nav-content {
    max-width: 1200px;
}

.rst-content .section > h1 {
    margin-bottom: 24px;
    color: #2c3e50;
}

Sphinx Extensions and Plugins

Core Extensions

Useful Third‑Party Extensions

Extension Configuration

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx_copybutton',
    'sphinx_autodoc_typehints',
]

# TODO settings
todo_include_todos = True

# intersphinx settings
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'numpy': ('https://numpy.org/doc/stable/', None),
    'pandas': ('https://pandas.pydata.org/docs/', None),
}

Sphinx Methods and Functions

Core autodoc Directives

autodoc Options

Cross‑Reference Directives

Integration with External Libraries

Configuring intersphinx

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'numpy': ('https://numpy.org/doc/stable/', None),
    'pandas': ('https://pandas.pydata.org/docs/', None),
    'matplotlib': ('https://matplotlib.org/stable/', None),
    'requests': ('https://requests.readthedocs.io/en/latest/', None),
}

Using External Links

The function uses :class:'numpy.ndarray' for data processing.
For HTTP requests, :class:'requests.Session' is employed.

Building the Documentation

Core Build Commands

Manual Build

# Build HTML
sphinx-build -b html source/ build/html

# Build PDF
sphinx-build -b latex source/ build/latex
cd build/latex && make

# Build with warnings as errors
sphinx-build -W -b html source/ build/html

Build Configuration

# In conf.py
html_output_encoding = 'utf-8'
html_use_index = True
html_split_index = True
html_show_sourcelink = True
html_show_sphinx = True
html_show_copyright = True

# Exclude patterns from the build
exclude_patterns = ['_build', '**.ipynb_checkpoints']

Automation and CI/CD

GitHub Actions

Create the file .github/workflows/docs.yml:

name: Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  docs:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'
    
    - name: Install dependencies
      run: |
        pip install sphinx sphinx-rtd-theme myst-parser
        pip install -r requirements.txt
    
    - name: Build documentation
      run: |
        cd docs
        make html
    
    - name: Deploy to GitHub Pages
      if: github.ref == 'refs/heads/main'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs/_build/html

GitLab CI

Create the file .gitlab-ci.yml:

stages:
  - docs

docs:
  stage: docs
  image: python:3.9
  script:
    - pip install sphinx sphinx-rtd-theme myst-parser
    - pip install -r requirements.txt
    - cd docs
    - make html
  artifacts:
    paths:
      - docs/_build/html
  only:
    - main

Publishing Documentation

Read the Docs

Read the Docs is a popular platform for hosting documentation:

1. Sign up at readthedocs.org
2. Connect your Git repository
3. Create a requirements.txt file with dependencies
4. Configure the .readthedocs.yml file

Example .readthedocs.yml:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.9"

sphinx:
  configuration: docs/conf.py

python:
  install:
    - requirements: requirements.txt
    - method: pip
      path: .

GitHub Pages

To publish on GitHub Pages:

1. Create a gh-pages branch
2. Copy the contents of _build/html to the root of the branch
3. Enable GitHub Pages in the repository settings

Netlify

To deploy on Netlify:

1. Connect the repository to Netlify
2. Set the build command: cd docs && make html
3. Specify the publish directory: docs/_build/html

Docstring Styles

Google Style

def function(arg1, arg2):
    """Brief description of the function.
    
    More detailed description of the function that may
    span multiple lines.
    
    Args:
        arg1 (str): Description of the first argument.
        arg2 (int): Description of the second argument.
    
    Returns:
        bool: Description of the return value.
    
    Raises:
        ValueError: Description of the exception.
    
    Example:
        >>> function("hello", 42)
        True
    """
    return True

NumPy Style

def function(arg1, arg2):
    """Brief description of the function.
    
    More detailed description of the function.
    
    Parameters
    ----------
    arg1 : str
        Description of the first argument.
    arg2 : int
        Description of the second argument.
    
    Returns
    -------
    bool
        Description of the return value.
    
    Raises
    ------
    ValueError
        Description of the exception.
    
    Examples
    --------
    >>> function("hello", 42)
    True
    """
    return True

Sphinx Style

def function(arg1, arg2):
    """Brief description of the function.
    
    More detailed description of the function.
    
    :param arg1: Description of the first argument
    :type arg1: str
    :param arg2: Description of the second argument
    :type arg2: int
    :returns: Description of the return value
    :rtype: bool
    :raises ValueError: Description of the exception
    
    .. code-block:: python
    
        >>> function("hello", 42)
        True
    """
    return True

Best Practices

Organizing the Structure

Recommended documentation layout:

docs/
├── conf.py
├── index.rst
├── installation.rst
├── quickstart.rst
├── user_guide/
│   ├── index.rst
│   ├── basic_usage.rst
│   └── advanced_usage.rst
├── api/
│   ├── index.rst
│   └── modules.rst
├── examples/
│   ├── index.rst
│   └── tutorial.rst
├── changelog.rst
└── contributing.rst

Writing Tips

1. Start with a concise description — the first line should be clear and informative
2. Include examples — add code samples for complex functions
3. Document parameters — specify types and purpose of all parameters
4. Document exceptions — list possible errors
5. Keep it up to date — update the docs alongside the code

Quality Checks

Use tools to verify documentation quality:

# Check documentation coverage
sphinx-build -b coverage docs docs/_build/coverage

# Check links
sphinx-build -b linkcheck docs docs/_build/linkcheck

# Check syntax (treat warnings as errors)
sphinx-build -W -b html docs docs/_build/html

Frequently Asked Questions

What is Sphinx and how does it differ from other documentation generators?

Sphinx is a powerful documentation generator specifically designed for Python projects. It stands out from other tools by its ability to automatically extract documentation from docstrings, its rich extension ecosystem, and its capability to generate documentation in many formats.

Can I use Markdown instead of reStructuredText?

Yes, with the MyST‑parser extension you can write documentation in Markdown while retaining full Sphinx directive support.

How do I set up automatic documentation generation from code?

Use the sphinx.ext.autodoc extension and the sphinx-apidoc command to create documentation files. Ensure your module paths are correctly configured in conf.py.

Which theme should I choose?

For most projects the Read the Docs theme (sphinx_rtd_theme) is recommended due to its popularity and feature set. For modern projects the Furo theme is also a great choice.

Can I publish documentation for free?

Yes, there are many free hosting platforms: Read the Docs, GitHub Pages, GitLab Pages, Netlify. Read the Docs is especially convenient for Python projects.

How do I integrate Sphinx with CI/CD systems?

Create configuration files for GitHub Actions, GitLab CI, or other systems that automatically build and publish the documentation on repository changes.

How do I add mathematical formulas to the documentation?

Use the sphinx.ext.mathjax or sphinx.ext.imgmath extensions to support LaTeX formulas.

Can I create diagrams in Sphinx?

Yes, extensions like sphinxcontrib-mermaid, sphinxcontrib-plantuml, or sphinx.ext.graphviz allow embedding various diagram types.

How can I keep the documentation synchronized with the code?

Use docstrings in the code, automatic documentation tests with sphinx.ext.doctest, and set up CI/CD to automatically verify and update the docs.

What should I do if the documentation build takes too long?

Optimize the build process by using incremental builds, excluding unnecessary files, and configuring caching in CI/CD systems.

Sphinx is a powerful and flexible tool for creating professional documentation. By following the recommendations in this guide, you can produce high‑quality documentation that serves both users and developers of your project.

$