Split tutorial in several files

Author: astrojuanlu

doc/tutorial/end.rst

@@ -0,0 +1,6 @@
+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/tutorial/first-steps.rst

@@ -0,0 +1,91 @@
+First steps to document your project using Sphinx
+=================================================
+
+Building your HTML documentation
+--------------------------------
+
+The ``index.rst`` file that ``sphinx-quickstart`` created has some content
+already, and it gets rendered as the front page of your HTML documentation.  It
+is written in reStructuredText, a powerful markup language.
+
+Modify the file as follows:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   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 :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:
+
+.. code-block:: console
+
+   (.venv) $ cd docs
+   (.venv) $ make html
+
+After running this command, you will see that ``index.html`` reflects the new
+changes!
+
+Building your documentation in other formats
+--------------------------------------------
+
+Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
+:ref:`and more <builders>`.  For example, to build your documentation
+in EPUB format, run this command from the ``docs`` directory:
+
+.. code-block:: console
+
+   (.venv) $ make epub
+
+After that, you will see the files corresponding to the e-book under
+``docs/build/epub/``.  You can either open ``Lumache.epub`` with an
+EPUB-compatible e-book viewer, like `Calibre <https://calibre-ebook.com/>`_,
+or preview ``index.xhtml`` on a web browser.
+
+.. note::
+
+   To quickly display a complete list of possible output formats, plus some
+   extra useful commands, you can run :code:`make help`.
+
+Each output format has some specific configuration options that you can tune,
+:ref:`including EPUB <epub-options>`.  For instance, the default value of
+:confval:`epub_show_urls` is ``inline``, which means that, by default, URLs are
+shown right after the corresponding link, in parentheses.  You can change that
+behavior by adding the following code at the end of your ``conf.py``:
+
+.. code-block:: python
+
+   # EPUB options
+   epub_show_urls = 'footnote'
+
+With this configuration value, and after running ``make epub`` again, you will
+notice that URLs appear now as footnotes, which avoids cluttering the text.
+Sweet!
+
+.. note::
+
+   Generating a PDF using Sphinx can be done running ``make latexpdf``,
+   provided that the system has a working LaTeX installation,
+   as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`.
+   Although this is perfectly feasible, such installations are often big,
+   and in general LaTeX requires careful configuration in some cases,
+   so PDF generation is out of scope for this tutorial.

doc/tutorial/getting-started.rst

@@ -0,0 +1,119 @@
+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:: rst
+   :caption: README.rst
+
+   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:`root 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:
+
+.. figure:: /_static/tutorial/lumache-first-light.png
+   :width: 80%
+   :align: center
+   :alt: Freshly created documentation of Lumache
+
+   Freshly created documentation of Lumache
+
+There we go! You created your first HTML documentation using Sphinx.