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:

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 <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 "*emphasis*" (typically italics),

* an **inline external link**,

* and a "note" **admonition** (one of the available 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!


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 "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.  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! Read on to explore 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
  "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.
