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 :ref:`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 press Enter. -> Project name
: Write "Lumache
" (without quotes) and press Enter. -> Author name(s)
: Write "Graziella
" (without quotes) and press Enter. -> Project release []
: Write "0.1
" (without quotes) and press Enter. -> Project language [en]
: Leave it empty (the default, English) and press Enter.
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
and Makefile
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 :term:`master 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 our 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 :ref:`rst-inline-markup`:**strong emphasis**
(typically bold) and*emphasis*
(typically italics), - an inline external link, - and anote
admonition (one of the available :ref:`directives <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!
This tutorial covered the very first steps to create a documentation project with Sphinx. To continue learning more about Sphinx, check out the :ref:`rest of the documentation <contents>`.