Getting started¶

Setting up your project and development environment¶

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

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:

$ 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 PyPI package. 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:

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

(.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 Enter.
> Project name: Write "Lumache" (without quotes) and press Enter.
> Author name(s): Write "Graziella" (without quotes) and press Enter.
> Project release []: Write "0.1" (without quotes) and press Enter.
> Project language [en]: Leave it empty (the default, English) and press Enter.

After the last question, you will see the new docs directory with the following content.

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

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

Freshly created documentation of Lumache¶

There we go! You created your first HTML documentation using Sphinx. Now you can start customizing it.