IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Rewrap text

Browse Source
This commit is contained in:
Juan Luis Cano Rodríguez 2021-06-06 17:19:39 +02:00
parent a2a8a07430
commit aee105ce46
1 changed files with 72 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
doc/tutorial/index.rst
View File

@ -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 <https://breathe.readthedocs.io/>`_.
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.
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 <https://world.openfoodfacts.org/>`_
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 <https://world.openfoodfacts.org/>`_ 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 <rst-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
<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:
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 <contents>`.
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>`.