Beginning of new Sphinx tutorial

doc/_templates/index.html

@@ -52,23 +52,25 @@ <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
         <p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
+        <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{%trans%}Tutorial{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}beginners tutorial{%endtrans%}</span></p>
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
       </td><td>
-      </td>
+        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+      </td><td>
     </tr>
   </table>
 

doc/contents.rst

@@ -7,6 +7,7 @@ Sphinx documentation contents
    :maxdepth: 2
 
    usage/index
+   tutorial/index
    development/index
    man/index
 

doc/tutorial/index.rst

@@ -0,0 +1,213 @@
+.. _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 <https://breathe.readthedocs.io/>`_.
+
+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 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>`.

doc/usage/installation.rst

@@ -185,6 +185,30 @@ 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 Installation
+and remove 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 like in some Linux distributions like Debian and Ubuntu
+   this might require an extra installation step::
+
+     $ apt-get install python3-venv
 
 Docker
 ------