First steps to document your project using Sphinx¶
Building your HTML documentation¶
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 Inline markup:
**strong emphasis**(typically bold) and
an inline external link,
noteadmonition (one of the available directives)
Now to render it with the new content, you can use the
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
Building your documentation in other formats¶
Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
and more. For example, to build your documentation
in EPUB format, run this command from the
(.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,
index.xhtml on a web browser.
To quickly display a complete list of possible output formats, plus some
extra useful commands, you can run
Each output format has some specific configuration options that you can tune,
including EPUB. For instance, the default value of
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
# 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.
Generating a PDF using Sphinx can be done running
provided that the system has a working LaTeX installation,
as explained in the documentation of
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.