First steps to document your project using Sphinx ================================================= Building your HTML documentation -------------------------------- 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: .. code-block:: rst :caption: docs/source/index.rst 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 `_ 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 a ``note`` **admonition** (one of the available :ref:`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: .. code-block:: console (.venv) $ cd docs (.venv) $ make html After running this command, you will see that ``index.html`` reflects the new changes! Building your documentation in other formats -------------------------------------------- Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, :ref:`and more `. For example, to build your documentation in EPUB format, run this command from the ``docs`` directory: .. code-block:: console (.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 :code:`make help`. Each output format has some specific configuration options that you can tune, :ref:`including EPUB `. For instance, the default value of :confval:`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``: .. code-block:: python # 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! Read on to explore :doc:`other ways to customize Sphinx `. .. 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 :class:`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.