Python Sphinx autodoc not rendering on readthedocs

Question

I have a Python package hosted on Github called spike2py. I have prepared my docs using Sphinx and .rst files. These files are hosted on GitHub here. I am able to successfully run make html locally and obtain the desired output. That is, the Reference Guide part of the documentation contains the API automatically generated using the docstring I have included in my code, and referenced using calls to autoclass and autofunction (reference_guide.rst).

For example, here is what the first part of the Reference Guide looks like when I render it locally:

However, when the documentation is rendered on readthedocs (see here), the Reference Guide does not contain the extracted doctrings; just the headers found in the .rst file.

Expected behaviour

I expected the docs rendered on readthedocs to be same as those rendered locally. However, this is not happening.

By looking here, I have confirmed that the version being presented on readthedocs in the current version of my documentation.

But when I try to download PDF or HTML versions of the documentation, the Reference Guide does not include the docstrings.

Other info

According to the readthedocs documentation, the local builds should not be pushed to GitHub; only the source files.

This is somewhat related to this issue, but I was not able to make the proposed solution work.

UPDATE I followed the solution recommended by Steve Piercy and this solved part of the problem. I added a docs/requirements.txt file as well as a .readthedocs.yml file.

Next I noticed that the build was using Python 3.7.9. Given that I was using type hints from Python >= 3.8, I had to specify the version of Python in the .readthedocs.yml file.

Then I was stuck with the RTD build telling me it can't find my index.rst file.

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/application.py", line 348, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 297, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 311, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 421, in read
    raise SphinxError('master file %s not found' %
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found

But I then solved this by specifying the following in my .readthedocs.yml:

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/source/conf.py

After this fix, the docs are built with what appears to be no errors and includes the following:

generating indices...  genindex py-modindexdone
highlighting module code... [ 20%] spike2py.channels
highlighting module code... [ 40%] spike2py.plot
highlighting module code... [ 60%] spike2py.read
highlighting module code... [ 80%] spike2py.sig_proc
highlighting module code... [100%] spike2py.trial

And yes, the doctrings appeared on RTD.

Playbook

This answer gives some insights into what is happening with your build on RTD, although the OP in that thread used a much more complicated setup. Anyway, if autodoc is building locally and on GitHub but not on RTD chances are it's because the RTD build can't import your modules (I'm not experienced enough on that site to pinpoint a solution, but this is the logic you should search for - I hope a more experienced member can contribute their analyses of the problem.) – Sammysamoan

Answer 1

Your project's dependencies are not specified on RTD, but you have installed the dependencies locally. You can verify this in the build log. Visit your project's Builds, click a build, and click "view raw".

WARNING: autodoc: failed to import class 'trial.TrialInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'trial.Trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'trial.load' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.ChannelInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Event' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Keyboard' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Waveform' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Wavemark' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'sig_proc.SignalProcessing' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'read.read' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)

To remedy the situation, you must specify that your project's dependencies must be installed. See Specifying Dependencies.

You must either:

1. Create a pip requirements file that specifies requirements, or
2. Create a file that specifies a pip install option which will install requirements that are already defined elsewhere, such as in a setup.py docs_requires stanza. See an example in the Pyramid repository with its rtd.txt and setup.py.

rtd.txt

-e .[docs]

setup.py

docs_extras = [
    'Sphinx >= 3.0.0',  # Force RTD to use >= 3.0.0
    'docutils',
    'pylons-sphinx-themes >= 1.0.8',  # Ethical Ads
    'pylons_sphinx_latesturl',
    'repoze.sphinx.autointerface',
    'sphinxcontrib-autoprogram',
]
# ...
    extras_require={'testing': testing_extras, 'docs': docs_extras},

One you have defined your project requirements in this file, then you must configure Read the Docs to recognize this file to install dependencies. The preferred method is to use a configuration file, but you can also do this through the project's Admin Dashboard.

Hallowell

Thanks for looking into this issue Steve. Your suggestion got me most of the way. However, as you will see in the update above, I am still having issues. – Sixtyfour

@MartinHéroux I just checked the built docs, and I see docstrings in the latest build. Is there still a problem? – Hallowell

All seems to work now! Great, and thanks. I guess I did not check the latest build...apologies, and thanks for the help. – Sixtyfour

Answer 2

I had exactly the same problem. Readthedocs could not extract the docstrings from my Project because it did not find my project module.

I solved this by adding 2 relative paths in the docs/conf.py:

sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))

So that now the top of the docs/conf.py looks as follows:

import os
import sys
import sphinx_rtd_theme

    # If extensions (or modules to document with autodoc) are in another directory,
    # add these directories to sys.path here. If the directory is relative to the
    # documentation root, use os.path.abspath to make it absolute, like shown here.
    sys.path.insert(0, os.path.abspath("."))
    sys.path.insert(0, os.path.abspath("../"))
    sys.path.insert(1, os.path.dirname(os.path.abspath("../")) + os.sep + "feature_engine")

Rubetta

Thanks for looking into this. Unfortunately this did not solve my problem. I already had the path to my module specified in the conf.py file; if this is not specified I cannot build the documentation locally on my own machine. When I do specify it, I can build the documentation locally. The problem is that RTD does not render the docstrings. Also, why import sphinx_rtd_theme? If is not used on conf.py. And what does the 3rd sys.path line do in your suggested answer? Thanks again for looking at this issue. – Sixtyfour