Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #9276 from astrojuanlu/new-tutorial
Beginning of new Sphinx tutorial
- Loading branch information
Showing
5 changed files
with
219 additions
and
5 deletions.
There are no files selected for viewing
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -7,6 +7,7 @@ Sphinx documentation contents | |
:maxdepth: 2 | ||
|
||
usage/index | ||
tutorial/index | ||
development/index | ||
man/index | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,185 @@ | ||
.. _tutorial: | ||
|
||
=============== | ||
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, | ||
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 <https://breathe.readthedocs.io/>`_. | ||
|
||
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 | ||
--------------- | ||
|
||
Setting up your project and development environment | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
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. | ||
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:`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:: 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: | ||
|
||
.. image:: /_static/tutorial/lumache-first-light.png | ||
|
||
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. | ||
|
||
Modify the file as 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 <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! | ||
|
||
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>`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters