Rewrap text

doc/tutorial/index.rst

@@ -4,32 +4,28 @@
 Sphinx tutorial
 ===============
 
-In this tutorial you will build a simple documentation project using Sphinx,
+In this tutorial you will build a simple documentation project using Sphinx, and
-and view it in your browser as HTML.
+view it in your browser as HTML.  The project will include narrative,
-The project will include narrative, handwritten documentation,
+handwritten documentation, as well as autogenerated API documentation.
-as well as autogenerated API documentation.
 
-The tutorial is aimed towards Sphinx newcomers
+The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
-willing to learn the fundamentals of how projects are created and structured.
+of how projects are created and structured.  You will create a fictional
-You will create a fictional software library to generate random food recipes
+software library to generate random food recipes that will serve as a guide
-that will serve as a guide throughout the process,
+throughout the process, with the objective of properly documenting it.
-with the objective of properly documenting it.
 
-To showcase Sphinx capabilities for code documentation
+To showcase Sphinx capabilities for code documentation you will use Python,
-you will use Python,
 which also supports *automatic* documentation generation.
 
 .. note::
 
-   Several other languages are natively supported in Sphinx
+   Several other languages are natively supported in Sphinx for *manual* code
-   for *manual* code documentation,
+   documentation, however they require extensions for *automatic* code
-   however they require extensions for *automatic* code documentation,
+   documentation, like `Breathe <https://breathe.readthedocs.io/>`_.
-   like `Breathe <https://breathe.readthedocs.io/>`_.
 
-To follow the instructions you will need access to a Linux-like command line
+To follow the instructions you will need access to a Linux-like command line and
-and a basic understanding of how it works,
+a basic understanding of how it works, as well as a working Python installation
-as well as a working Python installation for development,
+for development, since you will use *Python virtual environments* to create the
-since you will use *Python virtual environments* to create the project.
+project.
 
 Getting started
 ---------------
@@ -37,23 +33,20 @@ Getting started
 Setting up your project and development environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In a new directory,
+In a new directory, create a file called ``README.rst`` with the following
-create a file called ``README.rst``
+content.
-with the following content.
 
 .. code-block:: rest
 
    Lumache
    =======
 
-   **Lumache** (/luˈmake/) is a Python library for cooks and food lovers
+   **Lumache** (/luˈmake/) is a Python library for cooks and food lovers that
-   that creates recipes mixing random ingredients.
+   creates recipes mixing random ingredients.
 
-It is a good moment to create a Python virtual environment
+It is a good moment to create a Python virtual environment and install the
-and install the required tools.
+required tools.  For that, open a command line terminal, ``cd`` into the
-For that, open a command line terminal,
+directory you just created, and run the following commands:
-``cd`` into the directory you just created,
-and run the following commands:
 
 .. code-block:: console
 
@@ -63,14 +56,12 @@ and run the following commands:
 
 .. note::
 
-   The installation method used above
+   The installation method used above is described in more detail in
-   is described in more detail in :ref:`install-pypi`.
+   :ref:`install-pypi`.  For the rest of this tutorial, the instructions will
-   For the rest of this tutorial,
+   assume a Python virtual environment.
-   the instructions will assume a Python virtual environment.
 
-If you executed these instructions correctly,
+If you executed these instructions correctly, you should have the Sphinx command
-you should have the Sphinx command line tools available.
+line tools available.  You can do a basic verification running this command:
-You can do a basic verification running this command:
 
 .. code-block:: console
 
@@ -82,80 +73,63 @@ If you see a similar output, you are on the right path!
 Creating the documentation layout
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Then from the command line,
+Then from the command line, run the following command:
-run the following command:
 
 .. code-block:: console
 
    (.venv) $ sphinx-quickstart docs
 
-This will present to you a series of questions
+This will present to you a series of questions required to create the basic
-required to create the basic directory and configuration layout for your project
+directory and configuration layout for your project inside the ``docs`` folder.
-inside the ``docs`` folder.
 To proceed, answer each question as follows:
 
-- ``> Separate source and build directories (y/n) [n]``: Write "``y``"
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
-  (without quotes) and press :kbd:`Enter`.
+  quotes) and press :kbd:`Enter`.  - ``> Project name``: Write "``Lumache``"
-- ``> Project name``: Write "``Lumache``" (without quotes)
+  (without quotes) and press :kbd:`Enter`.  - ``> Author name(s)``: Write
-  and press :kbd:`Enter`.
+  "``Graziella``" (without quotes) and press :kbd:`Enter`.  - ``> Project
-- ``> Author name(s)``: Write "``Graziella``" (without quotes)
+  release []``: Write "``0.1``" (without quotes) and press :kbd:`Enter`.  - ``>
-  and press :kbd:`Enter`.
+  Project language [en]``: Leave it empty (the default, English) and press
-- ``> Project release []``: Write "``0.1``" (without quotes)
+  :kbd:`Enter`.
-  and press :kbd:`Enter`.
-- ``> Project language [en]``: Leave it empty (the default, English)
-  and press :kbd:`Enter`.
 
-After the last question,
+After the last question, you will see the new ``docs`` directory with the
-you will see the new ``docs`` directory with the following content.
+following content.
 
 .. code-block:: text
 
-	docs
+    docs ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├──
-	├── build
+    index.rst ├── _static └── _templates
-	├── make.bat
-	├── Makefile
-	└── source
-		├── conf.py
-		├── index.rst
-		├── _static
-		└── _templates
 
 The purpose of each of these files is:
 
 ``build/``
 
-  An empty directory (for now)
+  An empty directory (for now) that will hold the rendered documentation.
-  that will hold the rendered documentation.
 
 ``make.bat`` and ``Makefile``
 
-  Convenience scripts
+  Convenience scripts to simplify some common Sphinx operations, such as
-  to simplify some common Sphinx operations,
+  rendering the content.
-  such as rendering the content.
 
 ``source/conf.py``
 
-  A Python script holding the configuration of the Sphinx project.
+  A Python script holding the configuration of the Sphinx project.  It contains
-  It contains the project name and release you specified to ``sphinx-quickstart``,
+  the project name and release you specified to ``sphinx-quickstart``, as well
-  as well as some extra configuration keys.
+  as some extra configuration keys.
 
 ``source/index.rst``
 
-  The :term:`master document` of the project,
+  The :term:`master document` of the project, which serves as welcome page and
-  which serves as welcome page
+  contains the root of the "table of contents tree" (or *toctree*).
-  and contains the root of the "table of contents tree" (or *toctree*).
 
-Thanks to this bootstrapping step,
+Thanks to this bootstrapping step, you already have everything needed to render
-you already have everything needed
+the documentation as HTML for the first time.  To do that, run this command:
-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.
+And finally, open `docs/build/html/index.html` in your browser.  You should see
-You should see something like this:
+something like this:
 
 .. image:: /_static/tutorial/lumache-first-light.png
 
@@ -164,11 +138,9 @@ 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
+The ``index.rst`` file that ``sphinx-quickstart`` created has some content
-has some content already,
+already, and it gets rendered as the front page of our HTML documentation.  It
-and it gets rendered as the front page of our HTML documentation.
+is written in reStructuredText, a powerful markup language.
-It is written in reStructuredText,
-a powerful markup language.
 
 Modify the file as follows:
 
@@ -177,10 +149,10 @@ Modify the file as follows:
    Welcome to Lumache's documentation!
    ===================================
 
-   **Lumache** (/luˈmake/) is a Python library for cooks and food lovers
+   **Lumache** (/luˈmake/) is a Python library for cooks and food lovers that
-   that creates recipes mixing random ingredients.
+   creates recipes mixing random ingredients.  It pulls data from the `Open Food
-   It pulls data from the `Open Food Facts database <https://world.openfoodfacts.org/>`_
+   Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
-   and offers a *simple* and *intuitive* API.
+   *intuitive* API.
 
    .. note::
 
@@ -188,29 +160,26 @@ Modify the file as follows:
 
 This showcases several features of the reStructuredText syntax, including:
 
-- a **section header** using ``===`` for the underline,
+- a **section header** using ``===`` for the underline, - two examples of
-- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically bold)
+  :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically bold) and
-  and ``*emphasis*`` (typically italics),
+  ``*emphasis*`` (typically italics), - an **inline external link**, - and a
-- an **inline external link**,
+  ``note`` **admonition** (one of the available :ref:`directives
-- and a ``note`` **admonition** (one of the available
+  <rst-directives>`)
-  :ref:`directives <rst-directives>`)
 
-Now to render it with the new content,
+Now to render it with the new content, you can use the ``sphinx-build`` command
-you can use the ``sphinx-build`` command as before,
+as before, or leverage the convenience script as follows:
-or leverage the convenience script as follows:
 
 .. code-block:: console
 
    (.venv) $ cd docs
    (.venv) $ make html
 
-After running this command,
+After running this command, you will see that ``index.html`` reflects the new
-you will see that ``index.html`` reflects the new changes!
+changes!
 
 Where to go from here
 ---------------------
 
-This tutorial covered
+This tutorial covered the very first steps to create a documentation project
-the very first steps to create a documentation project with Sphinx.
+with Sphinx.  To continue learning more about Sphinx, check out the :ref:`rest
-To continue learning more about Sphinx,
+of the documentation <contents>`.
-check out the :ref:`rest of the documentation <contents>`.