From 70ee9bcd6accc8e67288e37d8976e43094ea9c74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 25 May 2021 10:56:22 +0200 Subject: [PATCH 01/17] Tutorial link in front page, audience, objectives, and prerequisites --- doc/_templates/index.html | 12 +++++++----- doc/contents.rst | 1 + doc/tutorial/index.rst | 25 +++++++++++++++++++++++++ 3 files changed, 33 insertions(+), 5 deletions(-) create mode 100644 doc/tutorial/index.rst diff --git a/doc/_templates/index.html b/doc/_templates/index.html index a37579c2925..a688d17c174 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -52,23 +52,25 @@

{%trans%}Documentation{%endtrans%}

{%trans%}First steps with Sphinx{%endtrans%}
{%trans%}overview of basic tasks{%endtrans%}

- {%- if hasdoc('search') %}

{%trans%}Search page{%endtrans%}
- {%trans%}search the documentation{%endtrans%}

{%- endif %} +

{%trans%}Tutorial{%endtrans%}
+ {%trans%}beginners tutorial{%endtrans%}

{%trans%}Contents{%endtrans%}
{%trans%}for a complete overview{%endtrans%}

- {%- if hasdoc('genindex') %}

{%trans%}General Index{%endtrans%}
- {%trans%}all functions, classes, terms{%endtrans%}

{%- endif %} + {%- if hasdoc('search') %}

{%trans%}Search page{%endtrans%}
+ {%trans%}search the documentation{%endtrans%}

{%- endif %}

{%trans%}Changes{%endtrans%}
{%trans%}release history{%endtrans%}

- + {%- if hasdoc('genindex') %}

{%trans%}General Index{%endtrans%}
+ {%trans%}all functions, classes, terms{%endtrans%}

{%- endif %} + diff --git a/doc/contents.rst b/doc/contents.rst index eb694629244..21a27e233cb 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -7,6 +7,7 @@ Sphinx documentation contents :maxdepth: 2 usage/index + tutorial/index development/index man/index diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 00000000000..81845c55921 --- /dev/null +++ b/doc/tutorial/index.rst @@ -0,0 +1,25 @@ +.. _tutorial: + +=============== +Sphinx tutorial +=============== + +In this tutorial you will build a simple documentation project using Sphinx, +and view it in your web browser as HTML. +We will include narrative, handwritten documentation, +as well as autogenerated API documentation. + +The tutorial is aimed towards people willing to learn +the fundamentals of Sphinx, +how projects are created and structured, +and how to contribute to an existing project. +To showcase Sphinx automatic documentation generation capabilities +we will use Python, which is the default :term:`domain`: +even though several other languages are supported, +they all work in a similar way. + +To follow the tutorial you will need a working Python installation for development. +We will use *Python virtual environments* to create our project, +you can read more about them in the `Python Packaging User Guide`_. + +.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment From 39b5564c630edcc0a2b84be874eb3285dda3de11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 26 May 2021 20:58:57 +0200 Subject: [PATCH 02/17] Beginning of the tutorial, tweaks to introduction --- doc/_static/tutorial/lumache-first-light.png | Bin 0 -> 52126 bytes doc/tutorial/index.rst | 152 +++++++++++++++++-- 2 files changed, 140 insertions(+), 12 deletions(-) create mode 100644 doc/_static/tutorial/lumache-first-light.png diff --git a/doc/_static/tutorial/lumache-first-light.png b/doc/_static/tutorial/lumache-first-light.png new file mode 100644 index 0000000000000000000000000000000000000000..fbf4aec8a3e4ea4d008f3159ee2891cccb5926ef GIT binary patch literal 52126 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 Hq2K=kw|3Yn literal 0 HcmV?d00001 diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 81845c55921..ef4d1fa9455 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -5,21 +5,149 @@ Sphinx tutorial =============== In this tutorial you will build a simple documentation project using Sphinx, -and view it in your web browser as HTML. -We will include narrative, handwritten documentation, +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 people willing to learn -the fundamentals of Sphinx, -how projects are created and structured, -and how to contribute to an existing project. +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 automatic documentation generation capabilities -we will use Python, which is the default :term:`domain`: -even though several other languages are supported, -they all work in a similar way. +you will use Python, which is the default :term:`domain` +(even though several other languages are supported, +they all work in a similar way). -To follow the tutorial you will need a working Python installation for development. -We will use *Python virtual environments* to create our project, -you can read more about them in the `Python Packaging User Guide`_. +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 +(you can read more about them in the `Python Packaging User Guide`_). .. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment + +Getting started +--------------- + +Setting up our project and development environment +.................................................. + +On a new directory, +create a file called ``README.rst`` +with the following contents: + +.. code-block:: rest + + 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:: bash + + $ 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:: bash + + (.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:: bash + + (.venv) $ sphinx-quickstart docs + +This will present you a series of questions +required to create the basic directory and configuration layout for your project +inside the `docs/` folder. +To proceed, introduce these answers: + +- ``> 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 some content:: + + docs/ + ├── build + ├── make.bat + ├── Makefile + └── source + ├── conf.py + ├── index.rst + ├── _static + └── _templates + +These files are: + +- ``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:`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: + +.. code-block:: bash + + (.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: + +.. image:: /_static/tutorial/lumache-first-light.png + +*Eccolo!* You created your first HTML documentation using Sphinx. + +.. todo:: + + To make this self-contained, we need: + + * Basic editing of the ``index.rst``, + * A mention to "next steps" to the rest of the documentation From 337ee6afaa3de8e698406b0077eca7e01e880d21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 27 May 2021 18:17:33 +0200 Subject: [PATCH 03/17] Style --- doc/tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index ef4d1fa9455..9da19fd54c7 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -143,7 +143,7 @@ You should see something like this: .. image:: /_static/tutorial/lumache-first-light.png -*Eccolo!* You created your first HTML documentation using Sphinx. +There we go! You created your first HTML documentation using Sphinx. .. todo:: From ffa8e110d0fd064d9e59c6fe58b7d25eaa666088 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 27 May 2021 21:32:49 +0200 Subject: [PATCH 04/17] Add index tweaks --- doc/tutorial/index.rst | 53 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 9da19fd54c7..1c1bad29be6 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -145,9 +145,54 @@ You should see something like this: There we go! You created your first HTML documentation using Sphinx. -.. todo:: +Making some tweaks to the index +............................... - To make this self-contained, we need: +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. - * Basic editing of the ``index.rst``, - * A mention to "next steps" to the rest of the documentation +Modify the file like follows: + +.. code-block:: rest + + 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. + + .. 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 **inline markup**: ``**bold**`` and ``*italics*``, +- an **inline external link**, +- and a ``note`` **admonition**. + +Now, to render it with the new content, +you can use the ``sphinx-build`` command as before, +or leverage the convenience script like this: + +.. code-block:: bash + + (.env) $ cd docs/ + (.env) $ make html + +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 `. From 1631291b0e63d02c9eb35ed6681093540b8cf66f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sat, 29 May 2021 13:21:47 +0200 Subject: [PATCH 05/17] Consistent heading styles --- doc/tutorial/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 1c1bad29be6..147c28c3dd9 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -32,7 +32,7 @@ Getting started --------------- Setting up our project and development environment -.................................................. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On a new directory, create a file called ``README.rst`` @@ -77,7 +77,7 @@ You can do a basic verification running this command: 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: @@ -146,7 +146,7 @@ You should see something like this: 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, From bfd3b51435c2903e1224d7ee15183e93630fb65a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sat, 29 May 2021 13:22:21 +0200 Subject: [PATCH 06/17] Style --- doc/tutorial/index.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 147c28c3dd9..60ddfd7b999 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -117,15 +117,26 @@ you will see the new ``docs`` directory with some content:: These files are: -- ``build/``: An empty directory (for now) +``build/`` + + An empty directory (for now) that will hold the rendered documentation. -- ``make.bat`` and ``Makefile``: Convenience scripts + +``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. + +``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:`master document` of the project, + +``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*). From d6cb2d0c38204989d4827e2c6f93fdd05fba3604 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sat, 29 May 2021 13:22:36 +0200 Subject: [PATCH 07/17] Use more appropriate terminology for emphasized text --- doc/tutorial/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 60ddfd7b999..52087db5ef0 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -184,7 +184,8 @@ Modify the file like follows: This showcases several features of the reStructuredText syntax, including: - a **section header** using ``===`` for the underline, -- two examples of **inline markup**: ``**bold**`` and ``*italics*``, +- two examples of **inline markup**: ``**strong emphasis**`` (typically bold) + and ``*emphasis*`` (typically italics), - an **inline external link**, - and a ``note`` **admonition**. From 5b3e5d887b680e326fc2eecda60af959cba7c3d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sat, 29 May 2021 13:44:26 +0200 Subject: [PATCH 08/17] Amend code documentation introduction --- doc/tutorial/index.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 52087db5ef0..2db15abd4d2 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -15,10 +15,16 @@ 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 automatic documentation generation capabilities -you will use Python, which is the default :term:`domain` -(even though several other languages are supported, -they all work in a similar way). +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 `_. To follow the instructions you will need access to a Linux-like command line and a basic understanding of how it works, From bfca913f1695969f8cb37bfde5ab8609b3b7a907 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sat, 29 May 2021 19:15:15 +0200 Subject: [PATCH 09/17] Move virtual environment explanation to installation --- doc/tutorial/index.rst | 5 +---- doc/usage/installation.rst | 24 ++++++++++++++++++++++++ 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 2db15abd4d2..d84b7d4424f 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -29,10 +29,7 @@ which also supports *automatic* documentation generation. 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 -(you can read more about them in the `Python Packaging User Guide`_). - -.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment +since you will use *Python virtual environments* to create the project. Getting started --------------- diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index f0384ea9dda..985f7fa340a 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -185,6 +185,30 @@ the ``--pre`` flag. $ pip install -U --pre sphinx +Using virtual environments +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When installing Sphinx using pip, +it is highly recommended to use *virtual environments*, +which isolate the Installation +and remove the need to use administrator privileges. +To create a virtual environment in the ``.venv`` directory, +use the following command. + +:: + + $ python -m venv .venv + +You can read more about them in the `Python Packaging User Guide`_. + +.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment + +.. warning:: + + Note like in some Linux distributions like Debian and Ubuntu + this might require an extra installation step:: + + $ apt-get install python3-venv Docker ------ From 1da5ab58083ddfa43b6a8dd57c20f3b672a809e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 31 May 2021 15:48:57 +0200 Subject: [PATCH 10/17] Style fixes Co-authored-by: Steve Piercy --- doc/tutorial/index.rst | 24 +++++++++++++----------- doc/usage/installation.rst | 11 +++++++---- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index d84b7d4424f..46810c40079 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -34,12 +34,12 @@ since you will use *Python virtual environments* to create the project. Getting started --------------- -Setting up our project and development environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Setting up your project and development environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On a new directory, +In a new directory, create a file called ``README.rst`` -with the following contents: +with the following content. .. code-block:: rest @@ -82,16 +82,16 @@ If you see a similar output, you are on the right path! Creating the documentation layout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Then, from the command line, +Then from the command line, run the following command: .. code-block:: bash (.venv) $ sphinx-quickstart docs -This will present you a series of questions +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. +inside the ``docs`` folder. To proceed, introduce these answers: - ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without quotes) @@ -106,7 +106,9 @@ To proceed, introduce these answers: and press :kbd:`Enter`. After the last question, -you will see the new ``docs`` directory with some content:: +you will see the new ``docs`` directory with the following content. + +.. code-block:: text docs/ ├── build @@ -168,7 +170,7 @@ and it gets rendered as the front page of our HTML documentation. It is written in reStructuredText, a powerful markup language. -Modify the file like follows: +Modify the file as follows. .. code-block:: rest @@ -192,9 +194,9 @@ This showcases several features of the reStructuredText syntax, including: - an **inline external link**, - and a ``note`` **admonition**. -Now, to render it with the new content, +Now to render it with the new content, you can use the ``sphinx-build`` command as before, -or leverage the convenience script like this: +or leverage the convenience script as follows. .. code-block:: bash diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 985f7fa340a..69468a4f26a 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -190,8 +190,8 @@ Using virtual environments When installing Sphinx using pip, it is highly recommended to use *virtual environments*, -which isolate the Installation -and remove the need to use administrator privileges. +which isolate the installed packages from the system packages, +thus removing the need to use administrator privileges. To create a virtual environment in the ``.venv`` directory, use the following command. @@ -205,8 +205,11 @@ You can read more about them in the `Python Packaging User Guide`_. .. warning:: - Note like in some Linux distributions like Debian and Ubuntu - this might require an extra installation step:: + Note that in some Linux distributions, such as Debian and Ubuntu, + this might require an extra installation step as follows. + + .. code-block:: bash + $ apt-get install python3-venv From 95519b3c067c54f3a3eddbdc528f8f7a7555c617 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 31 May 2021 16:22:37 +0200 Subject: [PATCH 11/17] Links to relevant reST syntax explanation --- doc/tutorial/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 46810c40079..05ea141af1c 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -189,10 +189,10 @@ Modify the file as follows. This showcases several features of the reStructuredText syntax, including: - a **section header** using ``===`` for the underline, -- two examples of **inline markup**: ``**strong emphasis**`` (typically bold) +- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically bold) and ``*emphasis*`` (typically italics), - an **inline external link**, -- and a ``note`` **admonition**. +- 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, From c8a3a2535a4471235008c51119c1a1a99f656392 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 31 May 2021 16:29:09 +0200 Subject: [PATCH 12/17] Be consistent with directory names --- doc/tutorial/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 05ea141af1c..cd103f6218c 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -110,7 +110,7 @@ you will see the new ``docs`` directory with the following content. .. code-block:: text - docs/ + docs ├── build ├── make.bat ├── Makefile @@ -200,7 +200,7 @@ or leverage the convenience script as follows. .. code-block:: bash - (.env) $ cd docs/ + (.env) $ cd docs (.env) $ make html After running this command, From 2b0131d0bcf3e87fcff3359ed3bb09e3e754e5ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 31 May 2021 16:29:55 +0200 Subject: [PATCH 13/17] Be consistent with virtual environment name --- doc/tutorial/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index cd103f6218c..87aec30249c 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -200,8 +200,8 @@ or leverage the convenience script as follows. .. code-block:: bash - (.env) $ cd docs - (.env) $ make html + (.venv) $ cd docs + (.venv) $ make html After running this command, you will see that ``index.html`` reflects the new changes! From ce727e3cfeced9e073e30e2722bba4721a08ad7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 31 May 2021 16:35:35 +0200 Subject: [PATCH 14/17] More style changes --- doc/tutorial/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 87aec30249c..68cb8b4cb8f 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -92,7 +92,7 @@ run the following command: 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, introduce these answers: +To proceed, answer each question as follows: - ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without quotes) and press :kbd:`Enter`. @@ -120,7 +120,7 @@ you will see the new ``docs`` directory with the following content. ├── _static └── _templates -These files are: +The purpose of each of these files is: ``build/`` @@ -170,7 +170,7 @@ 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. +Modify the file as follows: .. code-block:: rest @@ -196,7 +196,7 @@ This showcases several features of the reStructuredText syntax, including: Now to render it with the new content, you can use the ``sphinx-build`` command as before, -or leverage the convenience script as follows. +or leverage the convenience script as follows: .. code-block:: bash From 565713d2284b638d922255924faab49b619da6ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 31 May 2021 18:03:04 +0200 Subject: [PATCH 15/17] Change Pygments lexer to account for prompt --- doc/tutorial/index.rst | 10 +++++----- doc/usage/installation.rst | 5 ++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 68cb8b4cb8f..c42189fb9f3 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -55,7 +55,7 @@ For that, open a command line terminal, ``cd`` into the directory you just created, and run the following commands: -.. code-block:: bash +.. code-block:: console $ python -m venv .venv $ source .venv/bin/activate @@ -72,7 +72,7 @@ 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:: bash +.. code-block:: console (.venv) $ sphinx-build --version sphinx-build 4.0.2 @@ -85,7 +85,7 @@ Creating the documentation layout Then from the command line, run the following command: -.. code-block:: bash +.. code-block:: console (.venv) $ sphinx-quickstart docs @@ -150,7 +150,7 @@ you already have everything needed to render the documentation as HTML for the first time. To do that, run this command: -.. code-block:: bash +.. code-block:: console (.venv) $ sphinx-build -b html docs/source/ docs/build/html @@ -198,7 +198,7 @@ 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:: bash +.. code-block:: console (.venv) $ cd docs (.venv) $ make html diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 69468a4f26a..249b9a095cc 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -208,10 +208,9 @@ You can read more about them in the `Python Packaging User Guide`_. Note that in some Linux distributions, such as Debian and Ubuntu, this might require an extra installation step as follows. - .. code-block:: bash - + .. code-block:: console - $ apt-get install python3-venv + $ apt-get install python3-venv Docker ------ From a2a8a07430d21fe9e9c59f0d2eb930d85200b1bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sun, 6 Jun 2021 10:56:23 +0200 Subject: [PATCH 16/17] Adjust line length --- doc/tutorial/index.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index c42189fb9f3..b2f30df0aa6 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -94,8 +94,8 @@ 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`. +- ``> 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) @@ -192,7 +192,8 @@ This showcases several features of the reStructuredText syntax, including: - 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 `) +- 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, From aee105ce4681ad21bb78b6f3ef78fd55ebbd9f7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sun, 6 Jun 2021 17:19:39 +0200 Subject: [PATCH 17/17] Rewrap text --- doc/tutorial/index.rst | 179 +++++++++++++++++------------------------ 1 file changed, 74 insertions(+), 105 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index b2f30df0aa6..39ce7b697fd 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. - -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 `_. + 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 `.