SoFunction
Updated on 2025-05-07

A guide to getting started with Sphinx, a document generation tool in Python

In Python development, good documentation is one of the keys to project success. It not only helps developers understand the code, but also attracts and maintains more contributors. Sphinx is a powerful document generation tool that can convert concise reStructuredText or Markdown source files into well-formed documents such as HTML, LaTeX, PDF, etc. This article will take you to quickly get started with Sphinx and experience its powerful document generation capabilities through actual operations.

1. Install Sphinx

Before you start, make sure you have Python and pip installed. Next, install Sphinx using pip:

pip install sphinx

After the installation is complete, you can verify that the installation is successful through the command line:

sphinx-build --version

If you see the version number output, the installation is successful.

2. Create Sphinx Project

Initialize the project

In your project root directory, run the following command to initialize a Sphinx project:

sphinx-quickstart

This will start an interactive wizard that guides you through the configuration of the project.

  • Project name: Enter your project name, such as MyProject.
  • Author name(s): Enter the author name.
  • Project version: Enter the project version, such as 1.0.
  • Project release: Usually the same as the project version, or more information can be added, such as 1.0 alpha.
  • Source language: Default is en, that is, English.
  • Project language: also defaults to en.
  • Create a Makefile?: Enter y to create a Makefile for easier subsequent construction.
  • Create a Windows command file?: If you work on Windows, enter y.
  • Automatically insert docstrings from modules (y/n) [n]: Enter y to enable automatic document generation.
  • doctest: automatically test code snippets in doctest blocks (y/n) [n]: Enter y to enable doctest function.
  • intersphinx: link to the APIs of other projects (y/n) [n]: Select as needed, usually enter n.
  • todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: Select as needed, usually enter n.
  • coverage: checks for documentation coverage of your code (y/n) [n]: Select as needed, usually enter n.
  • PNG images with inline LaTeX: Select as needed, usually enter n.
  • Mathjax (for LaTeX and MathML support): Enter y to enable Mathjax support.
  • Epub output: Choose whether to generate Epub format documents according to your needs.
  • A custom theme: Enter a name or select n to use the default theme.
  • Path to theme or exclude and use default theme: If you select a custom theme, enter the theme path; otherwise, press Enter.
  • Names for HTML files: Usually keep the default.
  • Use separate folders for sources and build?: Enter y to separate source code and build file.
  • Dotfiles and hidden directories: Usually keep the default.

After completing the wizard, Sphinx will create a docs folder in your project directory, containing all the necessary configuration and template files.

Project structure

The docs folder structure is roughly as follows:

docs/
├── _build/              # Build the output directory
├── _static/         # Static files (CSS, JavaScript, images)
├── _templates/      # HTML templates
├──              # Configuration file
├──        # Main document file
└──       # Windows build script (if any)
└── Makefile   # Unix/Linux build script

3. Configure Sphinx

It is the core configuration file of Sphinx. Here you can set the metadata, extensions, themes, etc. of the project.

Basic configuration

# 
 
# Project Informationproject = 'MyProject'
author = 'Your Name'
version = '1.0'
release = '1.0'
 
# Language settingslanguage = 'en'
 
# Theme Settingshtml_theme = 'alabaster'  # One of the default themes, you can also select other themes 
# Static file pathhtml_static_path = ['_static']

Extended configuration

Sphinx supports a variety of extensions to enhance documentation capabilities. For example, enable can automatically extract document strings from Python modules.

# 
 
extensions = [
    '',
    '',
    '',
    '',
    '',
    '',
    '',
    '',
    '',  # If you are hosting on GitHub Pages]

Automatic document generation

In order for Sphinx to automatically extract documents from Python code, you need to set up autodoc-related configurations in it and use the corresponding instructions in your .rst file.

# 
 
# Automatic document generation settingsautodoc_member_order = 'bysource'  # Show members in source code orderautodoc_default_flags = ['members']  # Show all members

In your file, add module references:

.. toctree::
   :maxdepth: 2
   :caption: Contents:
 
modules

Then, create a file named in the docs directory to list the modules to be automatically documented:

MyProject Modules
=================
 
.. automodule:: myproject.module1
    :members:
 
.. automodule:: myproject.module2
    :members:

Make sure you have the appropriate documentation string in your Python code, for example:

# myproject/
 
def my_function():
    """
    This is a sample function.
 
    It does something useful.
    """
    pass

4. Build documents

In the docs directory, run the following command to build the HTML document:

make html

Or, if you are on Windows, use:

html

After the build is completed, you can find the generated HTML file in the _build/html directory. Open to view the document.

5. Practical cases

Suppose you have a simple Python project with the following structure:

myproject/
├── docs/
│   ├── _build/
│   ├── _static/
│   ├── _templates/
│   ├──
│   ├──
│   └──
├── myproject/
│   ├── __init__.py
│   ├──
│   └──
└──

and contains some simple functions and documentation strings.

Configuration

# 
 
project = 'MyProject'
author = 'Your Name'
version = '1.0'
release = '1.0'
 
extensions = [
    '',
]
 
templates_path = ['_templates']
exclude_patterns = []
html_theme = 'alabaster'
html_static_path = ['_static']

set up

Welcome to MyProject's documentation!
=====================================
 
.. toctree::
   :maxdepth: 2
   :caption: Contents:
 
   modules

create

MyProject Modules
=================
 
.. automodule:: myproject.module1
    :members:
 
.. automodule:: myproject.module2
    :members:

Writing Python code

# myproject/
 
def add(a, b):
    """
    Add two numbers.
 
    Args:
        a (int, float): The first number.
        b (int, float): The second number.
 
    Returns:
        int, float: The sum of a and b.
    """
    return a + b
 
# myproject/
 
def subtract(a, b):
    """
    Subtract the second number from the first.
 
    Args:
        a (int, float): The first number.
        b (int, float): The second number.
 
    Returns:
        int, float: The difference between a and b.
    """
    return a - b

Build a document

Run in the docs directory:

make html

Open _build/html/ and you will see the beautifully formatted document generated by Sphinx. The document will include function document strings extracted from and which are automatically inserted into the HTML page.

6. Further customization and optimization

Although Sphinx's default configuration and theme are already pretty good, you may also want to further customize and optimize according to your needs.

1. Use custom themes

Sphinx supports multiple themes, you can choose a theme that is more suitable for your project. For example, sphinx_rtd_theme is a popular theme that mimics the style of Read the Docs.

First, install the theme:

pip install sphinx_rtd_theme

Then, set the theme in:

html_theme = 'sphinx_rtd_theme'

2. Add custom CSS and JavaScript

You can further customize the appearance and behavior of the document by adding CSS and JavaScript files to the _static folder. In, make sure html_static_path contains the _static folder:

html_static_path = ['_static']

Then, create your CSS and JavaScript files in the _static folder and reference them in the HTML template.

3. Add additional pages and chapters

You can extend your document by creating new .rst files and adding them in the toctree directive. For example, you can create a file that contains more information about the project.

4. Use extensions

Sphinx has many extensions that can help you enhance the functionality of your documentation. For example, sphinxcontrib-bibtex can help you manage literature citations, and sphinxcontrib-spelling can help you check for spelling errors.

Add the extensions you need to in the extensions list:

extensions = [
    '',
    '',
    '',
    #Other extensions]

7. Deploy documents

Once you have generated the document, you may want to deploy it online so others can access it. There are many ways to do this, including using GitHub Pages, Read the Docs, or your own web server.

  • Using GitHub Pages
  • Build your document as HTML.
  • Push the generated HTML file to a branch of GitHub specifically for documents (usually gh-pages).
  • Enable GitHub Pages in the settings of the GitHub repository and select the correct branch.
  • Using Read the Docs
  • Register and log in on Read the Docs.
  • Import your GitHub repository.
  • Read the Docs will automatically build and host your documents.

8. Summary

Sphinx is a powerful document generation tool that can help you take documentation on Python projects to a professional level. With this article's guide, you should be able to get started with Sphinx quickly and start generating well-formatted documentation for your projects. As your familiarity with Sphinx grows, you can explore more advanced features and customization options to further improve your documentation.

The above is the detailed introduction guide for Sphinx, a powerful tool for document generation in Python. For more information about Python Sphinx, please follow my other related articles!