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
4 changes: 2 additions & 2 deletions docs/source/sphinx-config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Continuing, if we want Sphinx to autogenerate documentation from the comments of
import sys
sys.path.insert(0, os.path.abspath('../../simpleble/'))

Notice how we altered the path specified in line 3 (highlighted). This is because our ``conf.py`` file is located in ``simpleble-master/docs/source``, while our Python source codes, in this case the file ``simpleble.py``, are located inside ``simpleble-master/simpleble``. This means that when Sphinx is looking for our source codes, it now knows that it must go two directories up from ``conf.by`` (indicated by the ``../../`` part of the absolute path) and inside the folder ``simpleble-master/simpleble``. This is equivalent to adding the directory of our Python source files to PYTHONPATH.
Notice how we altered the path specified in line 3 (highlighted). This is because our ``conf.py`` file is located in ``simpleble-master/docs/source``, while our Python source codes, in this case the file ``simpleble.py``, are located inside ``simpleble-master/simpleble``. This means that when Sphinx is looking for our source codes, it now knows that it must go two directories up from ``conf.py`` (indicated by the ``../../`` part of the absolute path) and inside the folder ``simpleble-master/simpleble``. This is equivalent to adding the directory of our Python source files to PYTHONPATH.

**It is important to note here that the absolute path must be specified in relation to where** ``conf.py`` **resides, i.e. our `Sphinx source root`, rather than in relation to the `Documentation root`**.

Expand All @@ -53,4 +53,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.