New Sphinx tutorial, part II

doc/tutorial/index.rst

@@ -27,6 +27,9 @@ 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.
 
+.. contents:: Contents
+   :local:
+
 Getting started
 ---------------
 
@@ -134,18 +137,26 @@ the documentation as HTML for the first time.  To do that, run this command:
 
    (.venv) $ sphinx-build -b html docs/source/ docs/build/html
 
-And finally, open `docs/build/html/index.html` in your browser.  You should see
+And finally, open ``docs/build/html/index.html`` in your browser.  You should see
 something like this:
 
-.. image:: /_static/tutorial/lumache-first-light.png
+.. 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.
 
-Making some tweaks to the index
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+First steps to document your project using Sphinx
+-------------------------------------------------
+
+Converting your documentation to HTML
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
+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:
@@ -184,6 +195,243 @@ as before, or leverage the convenience script as follows:
 After running this command, you will see that ``index.html`` reflects the new
 changes!
 
+Exporting your documentation to other formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
+:ref:`and more <builders>`.  For example, to build your documentation as an
+e-book 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/html/``.  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!
+
+.. warning::
+
+   Generating a PDF using Sphinx can be done running ``make latexpdf``,
+   provided that the system has a working :math:`\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.
+
+More Sphinx customization using extensions
+------------------------------------------
+
+Enabling a built-in extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to these configuration values, you can customize Sphinx even more
+by using :doc:`extensions <../usage/extensions/index>`.  Sphinx ships several
+:ref:`built-in ones <built-in-extensions>`, and there are many more
+:ref:`maintained by the community <third-party-extensions>`.
+
+For example, to enable the :mod:`sphinx.ext.duration` extension,
+locate the ``extensions`` list in your ``conf.py`` and add one element as
+follows:
+
+.. code-block:: python
+
+   # Add any Sphinx extension module names here, as strings. They can be
+   # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+   # ones.
+   extensions = [
+       'sphinx.ext.duration',
+   ]
+
+After that, every time you generate your documentation, you will see a short
+durations report at the end of the console output, like this one:
+
+.. code-block:: console
+
+   (.venv) $ make html
+   ...
+   The HTML pages are in build/html.
+
+   ====================== slowest reading durations =======================
+   0.042 temp/source/index
+
+Using a third-party theme
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Themes, on the other hand, are a particular class of extensions that allow you
+to customize the appearance of your documentation.  Again, Sphinx has several
+:ref:`built-in themes <builtin-themes>`, and there are also third-party ones.
+
+For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
+in your HTML documentation, first you will need to install it with ``pip`` on
+your Python virtual environment, like this:
+
+.. code-block:: console
+
+   (.venv) $ pip install furo
+
+And then, locate the ``html_theme`` variable on your ``conf.py`` and replace
+its value as follows:
+
+.. code-block:: python
+
+   # The theme to use for HTML and HTML Help pages.  See the documentation for
+   # a list of builtin themes.
+   #
+   html_theme = 'alabaster'
+
+With this change, you will notice that your HTML documentation has now a new
+appearance:
+
+.. figure:: /_static/tutorial/lumache-furo.png
+   :width: 80%
+   :align: center
+   :alt: HTML documentation of Lumache with the Furo theme
+
+   HTML documentation of Lumache with the Furo theme
+
+Narrative documentation in Sphinx
+---------------------------------
+
+Inserting documents in the project hierarchy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As discussed at the beginning, ``index.rst`` is the :term:`master document`,
+whose main function is to serve as a welcome page and to contain the root of
+the "table of contents tree" (or *toctree*).  Sphinx allows you to assemble
+a project from different files, which is helpful when the project grows.
+
+As an example, create a new file ``docs/source/usage.rst`` (next to
+``index.rst``) with these contents:
+
+.. code-block:: rest
+
+   Usage
+   =====
+
+   Installation
+   ------------
+
+   To use Lumache, first install it using pip:
+
+   .. code-block:: console
+
+      (.venv) $ pip install lumache
+
+This new file contains two :ref:`section <rst-sections>` headers, normal
+paragraph text, and a ``code-block`` directive that renders a block of content
+as source code, with appropriate syntax highlighting (in this case, generic
+``console`` text).
+
+.. note::
+
+   You can read `the list of available highlight
+   languages <https://pygments.org/docs/lexers/>`_ in the Pygments
+   documentation.
+
+The structure of the document is determined by the succession of heading
+styles, which means that, by using ``---`` for the "Installation" section
+after ``===`` for the "Usage" section, you have declared "Installation" to
+be a *subsection* of "Usage".
+
+In addition, add a ``toctree`` :ref:`directive <rst-directives>` at the end
+of ``index.rst`` including the document you just created,
+as follows:
+
+.. code-block:: rest
+
+   Contents
+   --------
+
+   .. toctree::
+
+      usage
+
+This step inserts that document in the root of the *toctree*, so now it belongs
+to the structure of your project.  If you export the documentation to HTML
+running ``make html``, you will see that the ``toctree`` gets rendered as a
+list of hyperlinks, and this allows you to navigate to the new page you
+just created.  Neat!
+
+.. warning::
+
+   Every document should belong to a *toctree*.  Otherwise, Sphinx will emit a
+   ``WARNING: document isn't included in any toctree``, and the end result
+   will depend on the builder.  For the HTML builder, the page will not be
+   linked from anywhere (therefore it will not be discoverable), whereas for
+   the PDF builder, it will not be included at all.
+
+Adding cross-references
+~~~~~~~~~~~~~~~~~~~~~~~
+
+One powerful feature of Sphinx is the ability to seamlessly add
+:ref:`cross-references <xref-syntax>` to specific parts of the documentation:
+a document, a section, a figure, a code object, etc.  This tutorial is full of
+them!
+
+To add a straightforward cross-reference, write this sentence right after the
+introduction paragraph in ``index.rst``:
+
+.. code-block:: rest
+
+   Check out the :doc:`usage` section for further information.
+
+The :rst:role:`doc` role you used automatically references a specific document
+in the project, in this case the ``usage.rst`` you created earlier.
+
+Alternatively, you can also add a cross-reference to an arbitrary part of the
+project. For that, you need to use the :rst:role:`ref` role, and add an
+explicit *label* that can act as a target.
+
+For example, to reference the "Installation" subsection, add a label right
+before the heading, as follows:
+
+.. code-block:: rest
+
+   Usage
+   =====
+
+   .. _installation:
+
+   Installation
+   ------------
+
+   ...
+
+And make the sentence you added in ``index.rst`` look like this:
+
+.. code-block:: rest
+
+   Check out the :doc:`usage` section for further information, including how to
+   :ref:`install <installation>` the project.
+
+Notice a trick here: the ``install`` part specifies how the link will look like
+(we want it to be a specific word, so the sentence makes sense), whereas the
+``<installation>`` part refers to the actual label we want to add a
+cross-reference to. Both the ``:doc:`` and the ``:ref:`` roles will be rendered
+as hyperlinks in the HTML documentation.
+
 Where to go from here
 ---------------------
 

doc/usage/extensions/index.rst

@@ -10,6 +10,8 @@ This chapter describes the extensions bundled with Sphinx.  For the API
 documentation on writing your own extension, refer to :ref:`dev-extensions`.
 
 
+.. _built-in-extensions:
+
 Built-in extensions
 -------------------
 
@@ -38,6 +40,8 @@ These extensions are built in and can be activated by respective entries in the
    viewcode
 
 
+.. _third-party-extensions:
+
 Third-party extensions
 ----------------------
 

doc/usage/restructuredtext/basics.rst

@@ -224,6 +224,8 @@ Internal linking is done via a special reST role provided by Sphinx, see the
 section on specific markup, :ref:`ref-role`.
 
 
+.. _rst-sections:
+
 Sections
 --------