From 32f2f909acd8843f50a430ad11f2ac9dfd879373 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= <hello@juanlu.space>
Date: Mon, 6 Sep 2021 17:02:36 +0200
Subject: Simplify installation

---
 doc/tutorial/describing-code.rst | 74 ++++++++--------------------------------
 doc/tutorial/getting-started.rst |  2 --
 2 files changed, 15 insertions(+), 61 deletions(-)

(limited to 'doc/tutorial')

diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst
index 8988a8190..6bb18b342 100644
--- a/doc/tutorial/describing-code.rst
+++ b/doc/tutorial/describing-code.rst
@@ -127,71 +127,27 @@ documentation, called *doctests*, that are executed when the documentation is
 built.
 
 To demonstrate doctests and other Sphinx features covered in this tutorial,
-you will need to setup some basic Python infrastructure first.
-
-Preparing the Python library
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Begin by activating the virtual environment (as seen in the :ref:`getting
-started <tutorial-getting-started>` section of the tutorial) and install
-`flit <https://pypi.org/project/flit/>`_ on it:
-
-.. code-block:: console
-
-   $ source .venv/bin/activate
-   (.venv) $ python -m pip install "flit~=3.3"
-
-Next, create two files on the same level as ``README.rst``: ``pyproject.toml``
-and ``lumache.py``, with these contents:
-
-.. code-block:: toml
-   :caption: pyproject.toml
-
-   [build-system]
-   requires = ["flit_core >=3.2,<4"]
-   build-backend = "flit_core.buildapi"
-
-   [project]
-   name = "lumache"
-   authors = [{name = "Graziella", email = "graziella@lumache"}]
-   dynamic = ["version", "description"]
+Sphinx will need to be able to import the code. To achieve that, write this
+at the beginning of ``conf.py``:
 
 .. code-block:: python
-   :caption: lumache.py
-
-   """
-   Lumache - Python library for cooks and food lovers.
-   """
-
-   __version__ = "0.1.0"
-
-And finally, install your own code and check that importing it works:
-
-.. code-block:: console
-
-   (.venv) $ flit install --symlink
-   ...
-   (.venv) $ python -c 'import lumache; print("OK!")'
-   OK!
+   :caption: docs/source/conf.py
+   :emphasize-lines: 3-5
 
-Congratulations! You have created a basic Python library.
+   # If extensions (or modules to document with autodoc) are in another directory,
+   # add these directories to sys.path here.
+   import pathlib
+   import sys
+   sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
 
 .. note::
 
-   The ``pyproject.toml`` file you created above is required so that
-   your library can be installed. On the other hand,
-   ``flit install --symlink`` is an alternative to ``pip install .``
-   that removes the need to reinstall the library every time you make
-   a change, which is convenient.
-
-   An alternative is to not create ``pyproject.toml`` at all,
-   and setting the :envvar:`PYTHONPATH`, :py:data:`sys.path`, or
-   equivalent. However, the ``pyproject.toml`` approach is more robust.
-
-Adding some doctests to the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   An alternative to changing the :py:data:`sys.path` variable is to create a
+   ``pyproject.toml`` file and make the code installable,
+   so it behaves like any other Python library. However, the ``sys.path``
+   approach is simpler.
 
-To add doctests to your documentation, first enable the
+Then, before adding doctests to your documentation, enable the
 :doc:`doctest </usage/extensions/doctest>` extension in ``conf.py``:
 
 .. code-block:: python
@@ -203,7 +159,7 @@ To add doctests to your documentation, first enable the
        'sphinx.ext.doctest',
    ]
 
-Then, write a doctest block as follows:
+Next, write a doctest block as follows:
 
 .. code-block:: rst
    :caption: docs/source/usage.rst
diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst
index 40cf9bd4b..ccfa0952e 100644
--- a/doc/tutorial/getting-started.rst
+++ b/doc/tutorial/getting-started.rst
@@ -1,8 +1,6 @@
 Getting started
 ===============
 
-.. _tutorial-getting-started:
-
 Setting up your project and development environment
 ---------------------------------------------------
 
-- 
cgit v1.2.1