[Updated: May 25, 2025]

As developers, we all know the importance of writing a good document for our software, but composing a document may not be fun. Fortunately, a document-generating tool, Sphinx, makes the process simple and enjoyable. This tutorial demonstrates how to use Sphinx to build a high-quality and beautiful document.

How to Use Sphinx

Sphinx is a powerful document generator written in Python and the primary tool for generating documents for Python projects, including the official Python website. Because Sphinx is a document generator, not an editor like Microsoft Word, it works similarly to a compiler in building software. Sphinx supports reStructuredText (reST) and Markdown (MD) as its source file formats, and can generate HTML, PDF, and many other document formats.

Workflow

Using Sphinx is like working on a Python project: setting up the environment, composing the source files, and building the documents. Since reST is the default markup language, it is used in this section.

Step 1: Set up the environment

Install Sphinx in our Python workspace. Using a Python virtual environment is preferred.

$ python -m pip install sphinx

Sphinx comes with a tool, sphinx-quickstart, that sets up a skeleton project with a default configuration file, conf.py.

Assuming the root folder of our project is called sphinx-sample-rst, do the following.

$ mkdir sphinx-sample-rst
$ cd sphinx-sample-rst
$ sphinx-quickstart

After executing sphinx-quickstart, we will be asked to input some basic information about this project, and the conf.py will be generated according to our answers. The following is an example of the output.

$ sphinx-quickstart
Welcome to the Sphinx 8.2.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: Sphinx Sample
> Author name(s): Shun
> Project release []:

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:

Creating file /home/shun/workspace/sphinx-sample-rst/source/conf.py.
Creating file /home/shun/workspace/sphinx-sample-rst/source/index.rst.
Creating file /home/shun/workspace/sphinx-sample-rst/Makefile.
Creating file /home/shun/workspace/sphinx-sample-rst/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /home/shun/workspace/sphinx-sample-rst/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

After sphinx-quickstart completes setting up the project, a project skeleton will be generated as listed below.

sphinx-sample-rst
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

conf.py and index.rst are the most critical files.

The conf.py file is a configuration file for a Sphinx project, so it defines how we want to build the document (Similar to pyproject.toml in a Python project). For the complete list of built-in configuration values, see https://www.sphinx-doc.org/en/master/usage/configuration.html. Based on the input we provided when running sphinx-quickstart, the conf.py would look like the following.

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Sphinx Sample'
copyright = '2025, Shun'
author = 'Shun'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = []

templates_path = ['_templates']
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

The index.rst file defines the document layout and serves as a welcome page (like the index.html file in a webpage). Read Defining document structure for more details about defining the project structure and linking other pages.

Makefile and make.bat are the files used to build the document on Unix and Windows systems. The rest are placeholders for the document built, which are now empty.

Step 2: Compose reStructuredText files

Assuming our project contains a main page, a reference page, and a module page (the module page is under the package folder), add the following reST files to the corresponding folders.

source/main.rst

Main Page
=========

The main page that provides an overview of the project, its purpose, and how to use it.
It is typically written in **reStructuredText (reST)** format, which is a lightweight markup language used for writing documentation.

source/reference.rst

Reference
=========

List of references used in the documentation.

* `Sphinx <https://www.sphinx-doc.org/en/master/index.html>`_
* `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_

source/package/module.rst

Module
======

This module contains a class that displays a given value.

.. code-block:: python

    class MyClass:

        def __init__(self, value):
            self.value = value

        def display(self):
            return self.value

**Example**

This is an example of how to use the module.

.. code-block:: python

    from package import module

    my_class = module.MyClass(value=123)
    my_class.display()

To include those files, edit the index.rst as below.

Sphinx Document using reStructuredText
======================================

This is a sample of Sphinx document using reStructuredText.

.. toctree::
   :maxdepth: 2

   main
   package/module
   reference

After adding these files, the project layout will look like this.

sphinx-sample-rst
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    ├── main.rst
    ├── package
    │   └── module.rst
    └── reference.rst

Step 3: Build the document

Run the following command to build the document.

$ make html

(Use generating a webpage as an example. Check Builders for other formats.)

Once the document is generated, a folder, html, will be created in the build folder. Use any browser to open the index.html file located inside the build/html folder. A web-based document is ready to serve.

Use Markdown

The steps for using Markdown are the same as those for reStructuredText. However, Sphinx does not naturally support Markdown, and the sphinx-quickstart tool cannot generate a Markdown equivalent of index.rst. Therefore, to use Markdown, we need the following extra steps.

Install the Markdown parser, MyST-Parser.

$ python -m pip install myst-parser

Add myst_parser to the extensions list in the conf.py file.

extensions = ["myst_parser"]

Manually create an index.md file and delete the sphinx-quickstart generated index.rst (One project can only have one index file). A Markdown equivalent index file would look like the following.

index.md

# Sphinx Document using Markdown

This is a sample of Sphinx document using Markdown.

```{toctree}
main.md
package/module.md
reference.md
```

The rest of the Markdown files (i.e., main.md, module.md, and reference.md) are at sphinx-sample-documents/sphinx-sample-md/source at main · burpeesDaily/sphinx-sample-documents.

After the Markdown files are ready, run the same make html command to generate the document.

Auto-Generate Documents

The previous section demonstrates the basic workflow for using Sphinx to generate documents. One powerful feature of Sphinx is auto-generating documents from Python comments and docstrings. This section walks through the processes using an example, which assumes the reST format.

Step 1: Set up the environment

Set up a virtual environment, clone the sample, install Sphinx, and delete the existing docs folder (the demo will create it step-by-step).

$ git clone https://github.com/burpeesDaily/sphinx-sample-code.git
$ cd sphinx-sample-code
$ python -m pip install sphinx
$ rm -rf docs

The structure of the project looks like this.

sphinx-sample-code
├── LICENSE
├── README.rst
├── pyproject.toml
├── pytest.ini
├── requirements.txt
├── tests
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_avl_tree.py
│   ├── test_binary_search_tree.py
│   └── test_traversal.py
└── trees
    ├── __init__.py
    ├── binary_trees
    │   ├── __init__.py
    │   ├── avl_tree.py
    │   ├── binary_search_tree.py
    │   └── traversal.py
    └── tree_exceptions.py

Step 2: Set up the Sphinx project

Assuming all the document-related files are in a docs folder, we begin by creating it and then running sphinx-quickstart in it.

$ mkdir docs
$ cd docs
$ sphinx-quickstart

Now the project structure becomes the following.

sphinx-sample-code
├── LICENSE
├── README.rst
├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst
├── pyproject.toml
├── pytest.ini
├── requirements.txt
├── tests
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_avl_tree.py
│   ├── test_binary_search_tree.py
│   └── test_traversal.py
└── trees
    ├── __init__.py
    ├── binary_trees
    │   ├── __init__.py
    │   ├── avl_tree.py
    │   ├── binary_search_tree.py
    │   └── traversal.py
    └── tree_exceptions.py

Step 3: Configure the conf.py

Sphinx is highly configurable and extensible. Of course, the document theme is configurable. This example uses the Read the Docs Theme as its theme.  

• sphinx_rtd_theme is a Sphinx theme that provides a great reader experience similar to documents on Read the Docs.

The example also uses the following extensions to generate reST files.

• sphinx.ext.autodoc can import the Python modules we document using docstrings and comments and render them to the final document.
• sphinx.ext.napoleon is necessary for the sphinx.ext.autodoc extension so that it can understand NumPy or Google style docstrings (This example uses NumPy style).
• sphinx_copybutton is a third-party extension that adds a copy button to code blocks.

To use these extensions, we need to install them and add them to the conf.py file.

$ python -m pip install sphinx_rtd_theme
$ python -m pip install sphinx-copybutton

Note that sphinx.ext.autodoc and sphinx.ext.napoleon are shipped with Sphinx, so we do not need to install them separately.

Besides, to allow sphinx.ext.autodoc discover Python modules, we need to tell it where to find them. Add the following path configuration.

import os
import sys

sys.path.insert(0, os.path.abspath("../.."))

After adding them to the conf.py, the file will look like this.

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

import os
import sys

sys.path.insert(0, os.path.abspath("../.."))

project = "Spinx Sample"
copyright = "2025, Shun"
author = "Shun"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    "sphinx_rtd_theme",
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx_copybutton",
]

templates_path = ["_templates"]
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]

Step 4: Compose reStructuredText files

Before editing the index.rst file, we will create a few reST files corresponding to the Python modules and leverage the autodoc extension for generating documents.

Using avl_tree.py as an example, create an avl_tree.rst file under the source folder. In this file, we give a title and a brief introduction, and then enable the autodoc options, so it looks like the following:

AVL Tree
========

AVL trees are a type of self-balancing binary search tree. In an AVL tree, the heights of the two child subtrees of any node differ by at most one. If they differ by more than one at any time, rebalancing is performed to restore this property.

.. automodule:: trees.binary_trees.avl_tree
   :members:

We use the following syntax to tell the autodoc extension to generate a document for a given module.

.. automodule:: <module’s full name>
   :members:

The :members: option will generate a document for all members of the target module. The complete list of autodoc options is at sphinx.ext.autodoc – Include documentation from docstrings.

Repeat the same step to create binary_search_tree.rst for binary_search_tree.py and traversal.rst for traversal.py (Check the links for their details). Making a reST file for each Python module is mainly for easy maintenance. There is no restriction on how to organize the reST files. Adjust the mapping between the reST files and the Python source code accordingly.

Since the sphinx-sample-code project has a trees package that contains the binary_trees package and tree_exceptions.py, we create a trees.rst file for the tree_exceptions.py module, and also includes the avl_tree.rst, binary_search_tree.rst, and traversal.rst. The trees.rst looks like this.

Trees
=====

The **trees** package contains the following modules:

- **binary_trees**: Contains implementations of various types of binary trees.
- **tree_exceptions**: Defines exceptions related to tree operations.

Binary Trees
------------

.. toctree::
   :maxdepth: 2

   avl_tree
   binary_search_tree
   traversal



Tree exceptions
---------------

.. automodule:: trees.tree_exceptions
   :members:

Note that when including a reST file in the toctree, its extension can be omitted as long as it’s standard.

(Sphinx provides a CLI tool, sphinx-apidoc, to automatically generate reST files from Python modules. However, we will still need to adjust those reST files. Otherwise, the final document will look like a machine-generated document.)

Include the root README in the Sphinx document.

Almost all projects have a README file at the root level. Therefore, it would be nice to include the content of the root README in our Sphinx document, so we don’t need to duplicate its content. Unfortunately, Sphinx’s toctree directives (i.e., the index.rst file) can only include other files in the same project scope, e.g., the source folder in this example. But that is still doable – in an indirect way.

To include the root README file, we need to create a reST file, e.g., readme.rst, that includes the root README file and place the readme.rst file in the scope, e.g., the docs/source folder in this example.

.. include:: ../../README.rst

Assuming the root README also uses the reST format. To include README.md, use the same method, but the MyST-Parser extension is required.

Edit the index.rst file.

After all the reST files are composed, include them in the index.rst file, which will become the following.

Sphinx Sample Code documentation
================================

This is example documentation for the Sphinx Sample Code project using a tree library.
It contains a brief overview of the project, its modules, and some usage examples.

.. toctree::
   :maxdepth: 2

   readme
   trees

Step 5: Build the document

We can now build the document using the make html command. The document will look like this.

The document is also available at https://sphinx-sample-code.readthedocs.io/en/latest/.

Conclusion

Sphinx provides an easier way to build a professional document. It is also highly configurable and extensible. The workflow can be summarized as follows.

To learn more about Sphinx, check the following resources.

• Sphinx Official Website
• reStructuredText Primer
• reStructuredText Official Website
• Quick reStructuredText
• MyST Parser
• Sphinx — Read the Docs user documentation
• Awesome Sphinx