diff --git a/doc/_static/tutorial/lumache-first-light.png b/doc/_static/tutorial/lumache-first-light.png new file mode 100644 index 00000000000..fbf4aec8a3e Binary files /dev/null and b/doc/_static/tutorial/lumache-first-light.png differ diff --git a/doc/_templates/index.html b/doc/_templates/index.html index a37579c2925..a688d17c174 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -52,23 +52,25 @@

{%trans%}Documentation{%endtrans%}

{%trans%}First steps with Sphinx{%endtrans%}
{%trans%}overview of basic tasks{%endtrans%}

- {%- if hasdoc('search') %}

{%trans%}Search page{%endtrans%}
- {%trans%}search the documentation{%endtrans%}

{%- endif %} +

{%trans%}Tutorial{%endtrans%}
+ {%trans%}beginners tutorial{%endtrans%}

{%trans%}Contents{%endtrans%}
{%trans%}for a complete overview{%endtrans%}

- {%- if hasdoc('genindex') %}

{%trans%}General Index{%endtrans%}
- {%trans%}all functions, classes, terms{%endtrans%}

{%- endif %} + {%- if hasdoc('search') %}

{%trans%}Search page{%endtrans%}
+ {%trans%}search the documentation{%endtrans%}

{%- endif %}

{%trans%}Changes{%endtrans%}
{%trans%}release history{%endtrans%}

- + {%- if hasdoc('genindex') %}

{%trans%}General Index{%endtrans%}
+ {%trans%}all functions, classes, terms{%endtrans%}

{%- endif %} + diff --git a/doc/contents.rst b/doc/contents.rst index eb694629244..21a27e233cb 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -7,6 +7,7 @@ Sphinx documentation contents :maxdepth: 2 usage/index + tutorial/index development/index man/index diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 00000000000..39ce7b697fd --- /dev/null +++ b/doc/tutorial/index.rst @@ -0,0 +1,185 @@ +.. _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 capabilities for code documentation you will use Python, +which also supports *automatic* documentation generation. + +.. note:: + + Several other languages are natively supported in Sphinx for *manual* code + documentation, however they require extensions for *automatic* code + documentation, like `Breathe `_. + +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. + +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:: 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:: 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:`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:: console + + (.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 as 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 `_ 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! + +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 `. diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 49681f2ba96..8cf56b501db 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -185,6 +185,32 @@ the ``--pre`` flag. $ pip install -U --pre sphinx +Using virtual environments +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When installing Sphinx using pip, +it is highly recommended to use *virtual environments*, +which isolate the installed packages from the system packages, +thus removing the need to use administrator privileges. +To create a virtual environment in the ``.venv`` directory, +use the following command. + +:: + + $ python -m venv .venv + +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 + +.. warning:: + + Note that in some Linux distributions, such as Debian and Ubuntu, + this might require an extra installation step as follows. + + .. code-block:: console + + $ apt-get install python3-venv Docker ------