Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions docs/source/sphinx-config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,17 @@ Note that there exist numerous other nice themes out there, so if you're not par

Autodoc configuration
*********************
Continuing, if we want Sphinx to autogenerate documentation from the comments of our code using the ``autodoc`` extension, we have to point Sphinx to the directory in which our Python source codes reside. This can be done by uncommenting and altering the following lines, which are generally found at the top of the file:
Continuing, if we want Sphinx to autogenerate documentation from the comments of our code using the ``autodoc`` extension, we first have to enable it by adding its name to the ``extensions`` list:

.. code-block:: python
:emphasize-lines: 4

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [ 'sphinx.ext.autodoc' ]

Then its necessary to point Sphinx to the directory in which our Python source codes reside. This can be done by uncommenting and altering the following lines, which are generally found at the top of the file:

.. code-block:: python
:emphasize-lines: 3
Expand Down Expand Up @@ -53,4 +63,4 @@ Save and close the file (Ctrl+X -> Enter -> Y -> Enter).

Apart from specifying the dependencies of our package, the ``requirements.txt`` file can be used to batch install any such dependencies by calling ``sudo pip install -r requirements.txt``. For more information on requirements files, you can have a look at `pip's documentation <https://pip.pypa.io/en/stable/user_guide/#requirements-files>`_.

We will later also use the ``requirements.txt`` file when configuring the building process of our ReadTheDocs documentation. If we didn't have the requirements file, then ReadTheDocs would fail to run ``autodoc`` in order to generate our documentation from the comments in our source code. In other words, when building our documentation, RTD calls a ``pip install -r requirements.txt``, which installs any requirements in a virtual environment, which is then where ``sphinx-apidoc`` is run.
We will later also use the ``requirements.txt`` file when configuring the building process of our ReadTheDocs documentation. If we didn't have the requirements file, then ReadTheDocs would fail to run ``autodoc`` in order to generate our documentation from the comments in our source code. In other words, when building our documentation, RTD calls a ``pip install -r requirements.txt``, which installs any requirements in a virtual environment, which is then where ``sphinx-apidoc`` is run.