sphinx/doc/tutorial/index.rst

.. _tutorial:

===============
Sphinx tutorial
===============

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 automatic documentation generation capabilities
you will use Python, which is the default :term:`domain`
(even though several other languages are supported,
they all work in a similar way).

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
(you can read more about them in the `Python Packaging User Guide`_).

.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment

Getting started
---------------

Setting up our project and development environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On a new directory,
create a file called ``README.rst``
with the following contents:

.. code-block:: rest

   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:

.. code-block:: bash

   $ 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:

.. code-block:: bash

   (.venv) $ sphinx-build --version
   sphinx-build 4.0.2

If you see a similar output, you are on the right path!

Creating the documentation layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Then, from the command line,
run the following command:

.. code-block:: bash

   (.venv) $ sphinx-quickstart docs

This will present you a series of questions
required to create the basic directory and configuration layout for your project
inside the `docs/` folder.
To proceed, introduce these answers:

- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without quotes)
  and press :kbd:`Enter`.
- ``> Project name``: Write "``Lumache``" (without quotes)
  and press :kbd:`Enter`.
- ``> Author name(s)``: Write "``Graziella``" (without quotes)
  and press :kbd:`Enter`.
- ``> Project release []``: Write "``0.1``" (without quotes)
  and press :kbd:`Enter`.
- ``> Project language [en]``: Leave it empty (the default, English)
  and press :kbd:`Enter`.

After the last question,
you will see the new ``docs`` directory with some content::

	docs/
	├── build
	├── make.bat
	├── Makefile
	└── source
		├── conf.py
		├── index.rst
		├── _static
		└── _templates

These files are:

``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:

.. code-block:: bash

   (.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:

.. image:: /_static/tutorial/lumache-first-light.png

There we go! You created your first HTML documentation using Sphinx.

Making some tweaks to the index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 like follows:

.. code-block:: rest

   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**.

Now, to render it with the new content,
you can use the ``sphinx-build`` command as before,
or leverage the convenience script like this:

.. code-block:: bash

   (.env) $ cd docs/
   (.env) $ make html

After running this command,
you will see that ``index.html`` reflects the new changes!

Where to go from here
---------------------

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>`.