Rewrap text

doc/tutorial/index.rst

@@ -4,56 +4,49 @@
 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,
+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/>`_.
+   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.
+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.
+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.
+   **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:
+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
 
@@ -63,14 +56,12 @@ and run the following commands:
 
 .. 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.
+   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:
+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
 
@@ -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,
-run the following command:
+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.
+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`.
+- ``> 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.
+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
+    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.
+  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.
+  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.
+  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*).
+  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:
+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:
+And finally, open `docs/build/html/index.html` in your browser.  You should see
+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
-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.
+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:
 
@@ -177,40 +149,37 @@ Modify the file as follows:
    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.
+   **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 :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 <rst-directives>`)
+- 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
+  <rst-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:
+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!
+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>`.
+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>`.