Beginning of the tutorial, tweaks to introduction

doc/tutorial/index.rst

@@ -5,21 +5,149 @@ Sphinx tutorial
 ===============
 
 In this tutorial you will build a simple documentation project using Sphinx,
-and view it in your web browser as HTML.
-We will include narrative, handwritten documentation,
+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 people willing to learn
-the fundamentals of Sphinx,
-how projects are created and structured,
-and how to contribute to an existing project.
-To showcase Sphinx automatic documentation generation capabilities
-we will use Python, which is the default :term:`domain`:
-even though several other languages are supported,
-they all work in a similar way.
+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 follow the tutorial you will need a working Python installation for development.
-We will use *Python virtual environments* to create our project,
-you can read more about them in the `Python Packaging User Guide`_.
+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
+
+*Eccolo!* You created your first HTML documentation using Sphinx.
+
+.. todo::
+
+   To make this self-contained, we need:
+
+   * Basic editing of the ``index.rst``,
+   * A mention to "next steps" to the rest of the documentation