diff --git a/doc/_static/tutorial/lumache-furo.png b/doc/_static/tutorial/lumache-furo.png new file mode 100644 index 000000000..c7aaee796 Binary files /dev/null and b/doc/_static/tutorial/lumache-furo.png differ diff --git a/doc/glossary.rst b/doc/glossary.rst index 87b7014b6..ca12067c4 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -76,6 +76,9 @@ Glossary master document The document that contains the root :rst:dir:`toctree` directive. + root document + Same as :term:`master document`. + object The basic building block of Sphinx documentation. Every "object directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a diff --git a/doc/templating.rst b/doc/templating.rst index 0e9d38add..b25372319 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -115,7 +115,7 @@ The following blocks exist in the ``layout.html`` template: ``rootrellink``, ``relbaritems`` Inside the relbar there are three sections: The ``rootrellink``, the links from the documentation and the custom ``relbaritems``. The ``rootrellink`` - is a block that by default contains a list item pointing to the master + is a block that by default contains a list item pointing to the root document by default, the ``relbaritems`` is an empty block. If you override them to add extra links into the bar make sure that they are list items and end with the :data:`reldelim1`. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 993a308d3..6ff268695 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -36,7 +36,8 @@ Setting up your project and development environment In a new directory, create a file called ``README.rst`` with the following content. -.. code-block:: rest +.. code-block:: rst + :caption: README.rst Lumache ======= @@ -124,7 +125,7 @@ The purpose of each of these files is: as some extra configuration keys. ``source/index.rst`` - The :term:`master document` of the project, which serves as welcome page and + 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 @@ -134,23 +135,32 @@ 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 +------------------------------------------------- + +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 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: -.. code-block:: rest +.. code-block:: rst + :caption: docs/source/index.rst Welcome to Lumache's documentation! =================================== @@ -184,6 +194,256 @@ as before, or leverage the convenience script as follows: 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 `. 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 `_, +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 `. 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 :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 +------------------------- + +There are two main ways to customize your documentation beyond what is possible +with core Sphinx: extensions and themes. + +Enabling a built-in extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to these configuration values, you can customize Sphinx even more +by using :doc:`extensions `. Sphinx ships several +:ref:`builtin ones `, and there are many more +:ref:`maintained by the community `. + +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 + :caption: docs/source/conf.py + + # 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 HTML theme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Themes, on the other hand, are a way to customize the appearance of your +documentation. Sphinx has several :ref:`builtin themes `, and +there are also `third-party ones `_. + +For example, to use the `Furo `_ third-party theme +in your HTML documentation, first you will need to install it with ``pip`` in +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 + :caption: docs/source/conf.py + + # The theme to use for HTML and HTML Help pages. See the documentation for + # a list of builtin themes. + # + html_theme = 'furo' + +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 +--------------------------------- + +Structuring your documentation across multiple pages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root +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:: rst + :caption: docs/source/usage.rst + + Usage + ===== + + Installation + ------------ + + To use Lumache, first install it using pip: + + .. code-block:: console + + (.venv) $ pip install lumache + +This new file contains two :ref:`section ` headers, normal +paragraph text, and a :rst:dir:`code-block` directive that renders +a block of content as source code, with appropriate syntax highlighting +(in this case, generic ``console`` text). + +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". + +To complete the process, add a ``toctree`` :ref:`directive ` at +the end of ``index.rst`` including the document you just created, as follows: + +.. code-block:: rst + :caption: docs/source/index.rst + + Contents + -------- + + .. toctree:: + + usage + +This step inserts that document in the root of the *toctree*, so now it belongs +to the structure of your project, which so far looks like this: + +.. code-block:: text + + index + └── usage + +If you build the HTML documentation 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:: + + Documents outside a *toctree* will result in ``WARNING: document isn't + included in any toctree`` messages during the build process, and will be + unreachable for users. + +Adding cross-references +~~~~~~~~~~~~~~~~~~~~~~~ + +One powerful feature of Sphinx is the ability to seamlessly add +:ref:`cross-references ` 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 cross-reference, write this sentence right after the +introduction paragraph in ``index.rst``: + +.. code-block:: rst + :caption: docs/source/index.rst + + 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 acts as `a target`__. + +__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets + +For example, to reference the "Installation" subsection, add a label right +before the heading, as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + :emphasize-lines: 4 + + Usage + ===== + + .. _installation: + + Installation + ------------ + + ... + +And make the sentence you added in ``index.rst`` look like this: + +.. code-block:: rst + :caption: docs/source/index.rst + + Check out the :doc:`usage` section for further information, including how to + :ref:`install ` 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 +```` part refers to the actual label we want to add a +cross-reference to. If you do not include an explicit title, hence using +``:ref:`installation```, the section title will be used (in this case, +``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered +as hyperlinks in the HTML documentation. + Where to go from here --------------------- diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst index f4dfb7f66..7f993e10c 100644 --- a/doc/usage/advanced/setuptools.rst +++ b/doc/usage/advanced/setuptools.rst @@ -164,7 +164,7 @@ Options for setuptools integration .. setuptools-confval:: link-index - A boolean that ensures index.html will be linked to the master doc. Default + A boolean that ensures index.html will be linked to the root doc. Default is false. This can also be set by passing the `-i` flag to ``setup.py``: diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index 74853fee9..4d5315227 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -51,7 +51,7 @@ The builder's "name" must be given to the **-b** command-line option of This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like - the master document. No indices will be generated. + the root document. No indices will be generated. .. autoattribute:: name diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst index 0d446cb61..37d71c503 100644 --- a/doc/usage/extensions/index.rst +++ b/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`. +.. _builtin-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 ---------------------- diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index 83b5211bd..8644a0021 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -48,8 +48,8 @@ Defining document structure --------------------------- Let's assume you've run :program:`sphinx-quickstart`. It created a source -directory with :file:`conf.py` and a master document, :file:`index.rst`. The -main function of the :term:`master document` is to serve as a welcome page, and +directory with :file:`conf.py` and a root document, :file:`index.rst`. The +main function of the :term:`root document` is to serve as a welcome page, and to contain the root of the "table of contents tree" (or *toctree*). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents. @@ -74,14 +74,14 @@ multiple files to a single hierarchy of documents. The ``toctree`` directive initially is empty, and looks like so: -.. code-block:: rest +.. code-block:: rst .. toctree:: :maxdepth: 2 You add documents listing them in the *content* of the directive: -.. code-block:: rest +.. code-block:: rst .. toctree:: :maxdepth: 2 @@ -172,7 +172,7 @@ The most prominent domain is the Python domain. For example, to document Python's built-in function ``enumerate()``, you would add this to one of your source files. -.. code-block:: restructuredtext +.. code-block:: rst .. py:function:: enumerate(sequence[, start=0]) @@ -193,7 +193,7 @@ given, each in its own line. The Python domain also happens to be the default domain, so you don't need to prefix the markup with the domain name. -.. code-block:: restructuredtext +.. code-block:: rst .. function:: enumerate(sequence[, start=0]) diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 1c601ea2e..d96b1fe38 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/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 -------- diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 24f3af9d8..2a9743e94 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -497,10 +497,10 @@ __ https://pygments.org/docs/lexers Some Ruby code. The directive's alias name :rst:dir:`sourcecode` works as well. This - directive takes a language name as an argument. It can be any lexer alias - supported by Pygments. If it is not given, the setting of - :rst:dir:`highlight` directive will be used. If not set, - :confval:`highlight_language` will be used. + directive takes a language name as an argument. It can be `any lexer alias + supported by Pygments `_. If it is not + given, the setting of :rst:dir:`highlight` directive will be used. + If not set, :confval:`highlight_language` will be used. .. versionchanged:: 2.0 The ``language`` argument becomes optional.