In this tutorial you will build a simple documentation project using Sphinx, and view it in your browser as HTML. The project will include narrative, handwritten documentation, as well as autogenerated API documentation.
The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals of how projects are created and structured. You will create a fictional software library to generate random food recipes that will serve as a guide throughout the process, with the objective of properly documenting it.
To showcase Sphinx capabilities for code documentation you will use Python, which also supports automatic documentation generation.
Note
Several other languages are natively supported in Sphinx for manual code documentation, however they require extensions for automatic code documentation, like Breathe.
To follow the instructions you will need access to a Linux-like command line and a basic understanding of how it works, as well as a working Python installation for development, since you will use Python virtual environments to create the project.
In a new directory, create a file called README.rst
with the following content.
Lumache
=======
**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.
It is a good moment to create a Python virtual environment and install the required tools. For that, open a command line terminal, cd
into the directory you just created, and run the following commands:
$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx
Note
The installation method used above is described in more detail in install-pypi
. For the rest of this tutorial, the instructions will assume a Python virtual environment.
If you executed these instructions correctly, you should have the Sphinx command line tools available. You can do a basic verification running this command:
(.venv) $ sphinx-build --version
sphinx-build 4.0.2
If you see a similar output, you are on the right path!
Then from the command line, run the following command:
(.venv) $ sphinx-quickstart docs
This will present to you a series of questions required to create the basic directory and configuration layout for your project inside the docs
folder. To proceed, answer each question as follows:
> Separate source and build directories (y/n) [n]
: Write "y
" (without quotes) and pressEnter
.> Project name
: Write "Lumache
" (without quotes) and pressEnter
.> Author name(s)
: Write "Graziella
" (without quotes) and pressEnter
.> Project release []
: Write "0.1
" (without quotes) and pressEnter
.> Project language [en]
: Leave it empty (the default, English) and pressEnter
.
After the last question, you will see the new docs
directory with the following content.
docs
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
The purpose of each of these files is:
build/
An empty directory (for now) that will hold the rendered documentation.
make.bat
andMakefile
Convenience scripts to simplify some common Sphinx operations, such as rendering the content.
source/conf.py
A Python script holding the configuration of the Sphinx project. It contains the project name and release you specified to
sphinx-quickstart
, as well as some extra configuration keys.source/index.rst
The
root document
of the project, which serves as welcome page and contains the root of the "table of contents tree" (or toctree).
Thanks to this bootstrapping step, you already have everything needed to render the documentation as HTML for the first time. To do that, run this command:
(.venv) $ sphinx-build -b html docs/source/ docs/build/html
And finally, open docs/build/html/index.html
in your browser. You should see something like this:
There we go! You created your first HTML documentation using Sphinx.
The index.rst
file that sphinx-quickstart
created has some content already, and it gets rendered as the front page of your HTML documentation. It is written in reStructuredText, a powerful markup language.
Modify the file as follows:
Welcome to Lumache's documentation!
===================================
**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients. It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.
.. note::
This project is under active development.
This showcases several features of the reStructuredText syntax, including:
- a section header using
===
for the underline, - two examples of
rst-inline-markup
:**strong emphasis**
(typically bold) and*emphasis*
(typically italics), - an inline external link,
- and a
note
admonition (one of the availabledirectives <rst-directives>
)
Now to render it with the new content, you can use the sphinx-build
command as before, or leverage the convenience script as follows:
(.venv) $ cd docs
(.venv) $ make html
After running this command, you will see that index.html
reflects the new changes!
Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, and more <builders>
. For example, to build your documentation in EPUB format, run this command from the docs
directory:
(.venv) $ make epub
After that, you will see the files corresponding to the e-book under docs/build/epub/
. You can either open Lumache.epub
with an EPUB-compatible e-book viewer, like Calibre, or preview index.xhtml
on a web browser.
Note
To quickly display a complete list of possible output formats, plus some extra useful commands, you can run make help
.
Each output format has some specific configuration options that you can tune, including EPUB <epub-options>
. For instance, the default value of epub_show_urls
is inline
, which means that, by default, URLs are shown right after the corresponding link, in parentheses. You can change that behavior by adding the following code at the end of your conf.py
:
# EPUB options
epub_show_urls = 'footnote'
With this configuration value, and after running make epub
again, you will notice that URLs appear now as footnotes, which avoids cluttering the text. Sweet!
Note
Generating a PDF using Sphinx can be done running make latexpdf
, provided that the system has a working LaTeX installation, as explained in the documentation of sphinx.builders.latex.LaTeXBuilder
. Although this is perfectly feasible, such installations are often big, and in general LaTeX requires careful configuration in some cases, so PDF generation is out of scope for this tutorial.
There are two main ways to customize your documentation beyond what is possible with core Sphinx: extensions and themes.
In addition to these configuration values, you can customize Sphinx even more by using extensions </usage/extensions/index>
. Sphinx ships several builtin ones <builtin-extensions>
, and there are many more maintained by the community <third-party-extensions>
.
For example, to enable the sphinx.ext.duration
extension, locate the extensions
list in your conf.py
and add one element as follows:
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.duration',
]
After that, every time you generate your documentation, you will see a short durations report at the end of the console output, like this one:
(.venv) $ make html
...
The HTML pages are in build/html.
====================== slowest reading durations =======================
0.042 temp/source/index
Themes, on the other hand, are a way to customize the appearance of your documentation. Sphinx has several builtin themes <builtin-themes>
, and there are also third-party ones.
For example, to use the Furo third-party theme in your HTML documentation, first you will need to install it with pip
in your Python virtual environment, like this:
(.venv) $ pip install furo
And then, locate the html_theme
variable on your conf.py
and replace its value as follows:
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
With this change, you will notice that your HTML documentation has now a new appearance:
HTML documentation of Lumache with the Furo themeThe file index.rst
created by sphinx-quickstart
is the root
document
, whose main function is to serve as a welcome page and to contain the root of the "table of contents tree" (or toctree). Sphinx allows you to assemble a project from different files, which is helpful when the project grows.
As an example, create a new file docs/source/usage.rst
(next to index.rst
) with these contents:
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
This new file contains two section <rst-sections>
headers, normal paragraph text, and a :rstcode-block
directive that renders a block of content as source code, with appropriate syntax highlighting (in this case, generic console
text).
The structure of the document is determined by the succession of heading styles, which means that, by using ---
for the "Installation" section after ===
for the "Usage" section, you have declared "Installation" to be a subsection of "Usage".
To complete the process, add a toctree
directive <rst-directives>
at the end of index.rst
including the document you just created, as follows:
Contents
--------
.. toctree::
usage
This step inserts that document in the root of the toctree, so now it belongs to the structure of your project, which so far looks like this:
index
└── usage
If you build the HTML documentation running make html
, you will see that the toctree
gets rendered as a list of hyperlinks, and this allows you to navigate to the new page you just created. Neat!
Warning
Documents outside a toctree will result in WARNING: document isn't included in any toctree
messages during the build process, and will be unreachable for users.
One powerful feature of Sphinx is the ability to seamlessly add cross-references <xref-syntax>
to specific parts of the documentation: a document, a section, a figure, a code object, etc. This tutorial is full of them!
To add a cross-reference, write this sentence right after the introduction paragraph in index.rst
:
Check out the :doc:`usage` section for further information.
The :rstdoc
role you used automatically references a specific document in the project, in this case the usage.rst
you created earlier.
Alternatively, you can also add a cross-reference to an arbitrary part of the project. For that, you need to use the :rstref
role, and add an explicit label that acts as a target.
For example, to reference the "Installation" subsection, add a label right before the heading, as follows:
Usage
=====
.. _installation:
Installation
------------
...
And make the sentence you added in index.rst
look like this:
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
Notice a trick here: the install
part specifies how the link will look like (we want it to be a specific word, so the sentence makes sense), whereas the <installation>
part refers to the actual label we want to add a cross-reference to. If you do not include an explicit title, hence using :ref:`installation
, the section title will be used (in this case, Installation). Both the :doc: and the :ref:` roles will be rendered as hyperlinks in the HTML documentation.
This tutorial covered the very first steps to create a documentation project with Sphinx. To continue learning more about Sphinx, check out the rest
of the documentation <contents>
.