diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index b2f30df0a..39ce7b697 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -4,32 +4,28 @@ 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. +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. +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, +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 `_. + Several other languages are natively supported in Sphinx for *manual* code + documentation, however they require extensions for *automatic* code + documentation, like `Breathe `_. -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 --------------- @@ -37,23 +33,20 @@ 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,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 - that creates recipes mixing random ingredients. - It pulls data from the `Open Food Facts database `_ - 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 `_ and offers a *simple* and + *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, -- 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 `) +- 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 + `) -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 `. +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 `.