Getting started

Setting up your project and development environment

In a new directory, create a file called README.rst with the following content.

.. code-block:: rst :caption: README.rst

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

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

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

(.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 :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 the following content.

.. code-block:: text

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:root 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:: console

(.venv) $ sphinx-build -M html docs/source/ docs/build/

And finally, open docs/build/html/index.html in your browser. You should see something like this:

.. figure:: /_static/tutorial/lumache-first-light.png :width: 80% :align: center :alt: Freshly created documentation of Lumache

Freshly created documentation of Lumache

There we go! You created your first HTML documentation using Sphinx. Now you can start :doc:customizing it </tutorial/first-steps>.