Docstrings are not generated on Read the Docs with Sphinx autodoc and napoleon extensions

Question

I am using the Sphinx autodoc and napoleon extensions to generate the documentation for my project (Qtools). This works well on my local machines. I am using Sphinx 3.1.2 (or higher). However, when I build the documentation on Read the Docs (RTD), only text added directly to the reStructuredText files that form the source of the documentation is processed. The docstrings that are supposed to be pulled in by autodoc do not appear in the HTML documentation generated by RTD. So for example in docs\source\section2_rsdoc.rst I have:

Response spectra
================

The response spectrum class
---------------------------

.. autoclass:: qtools.ResponseSpectrum
   :members:

Response spectrum creation
--------------------------

.. autofunction:: qtools.calcrs

.. autofunction:: qtools.calcrs_cmp

.. autofunction:: qtools.loadrs

See also :func:`qtools.convert2rs` (converts a power spectrum into a response spectrum).

This results in:

---

Response spectra

The response spectrum class

Response spectrum creation

See also qtools.convert2rs (converts a power spectrum into a response spectrum).

---

In other words, all directives are apparently ignored, and hyperlinks to other functions are not added. I have examined several basic guidance documents such as this one, but I cannot figure out what I am doing wrong. RTD builds the documentation without any errors or warnings. In RTD advanced settings I have:

• Documentation type: Sphinx HTML
• Requirements file: requirements.txt
• Python interpreter: CPython 3.x
• Install Project: no
• Use system packages: no
• Python configuration file: blank
• Enable PDF build: no
• Enable EPUB build: no

I haven't touched any other settings.

In conf.py I have tried the following variations of line 15: sys.path.insert(0, os.path.abspath('.')), sys.path.insert(0, os.path.abspath('../..')) and the current sys.path.insert(0, os.path.abspath('../../..')). None of those made any difference.

I would be grateful for any help!

Answer 1

RTD builds the documentation without any errors or warnings

This is slightly incorrect. As you can see in the build logs, autodoc is emitting numerous warnings like this one:

WARNING: autodoc: failed to import class 'ResponseSpectrum' from module 'qtools'; the following exception was raised:
No module named 'qtools'

This has happened for all your variations of sys.path.insert, as you can see in some past builds.

Trying to make it work this way is tricky, since Read the Docs does some magic to guess the directory where your documentation is located, and also the working directory changes between commands.

Instead, there are two options:

• Locate where the conf.py is located (see How do you properly determine the current script directory?) and work out a relative package from there.
• Invest some time into making your code installable using up-to-date Python packaging standards, for example putting all your sources inside a qtools directory, and creating an appropriate pyproject.toml file using flit.