Read The Docs not working with automodule

Question

I've written some documentation for my project (in the Python docstrings), and tested everything with Sphinx on my local computer – everything works fine, all the import work correctly and so on. So I set up a custom environment on Read The Docs (Python 3, numpydoc and my library), added the docs directory (and the docs/source subdirectory) to my Github repo, and the build on Read The Docs passes, however, nothing is created (the View Docs link just shows a Nginx 404 page). The logs are as follows:

State: Finished

Outcome: Passed

Version: latest

Type: html
Sphinx Standard Output



html
-----

Making output directory...
Running Sphinx v1.2.2
loading translations [en]... done
building [readthedocs]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [ 20%] contents
reading sources... [ 40%] source/contents
reading sources... [ 60%] source/index
reading sources... [ 80%] source/kineticlib
reading sources... [100%] source/modules

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 20%] contents
writing output... [ 40%] source/contents
writing output... [ 60%] source/index
writing output... [ 80%] source/kineticlib
writing output... [100%] source/modules

writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 15 warnings.
Copying readthedocs-ext.js_t... done

Sphinx Standard Error



html
-----

/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:11: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.affinities
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:19: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.crosssection
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:27: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.errors
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:35: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.loaddata
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:43: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.omegaint
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:51: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.particles
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:59: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.probabilities
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:67: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.ratesdiss
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:75: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.ratesvibr
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:83: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.reltimes
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:91: ERROR: Unknown directive type "automodule".

.. automodule:: kineticlib.wtpoly
    :members:
    :undoc-members:
    :show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/contents.rst:: WARNING: document isn't included in any toctree
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/index.rst:: WARNING: document isn't included in any toctree
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/modules.rst:: WARNING: document isn't included in any toctree
WARNING: html_static_path entry '/var/build/user_builds/kineticlib/checkouts/latest/docs/_static' does not exist

Setup Output



checkout
-----



venv
-----

Using base prefix '/usr'
New python executable in /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/bin/python3
Not overwriting existing python script /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/bin/python (you must use /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/bin/python3)
Installing setuptools, pip...done.
Running virtualenv with interpreter /usr/bin/python3


sphinx
-----

Requirement already up-to-date: sphinx==1.2.2 in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages
Requirement already up-to-date: virtualenv==1.9.1 in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages
Requirement already up-to-date: docutils==0.11 in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages
Downloading/unpacking readthedocs-ext from git+git://github.com/ericholscher/readthedocs-sphinx-ext
  Cloning git://github.com/ericholscher/readthedocs-sphinx-ext to /var/build/user_builds/kineticlib/envs/latest/build/readthedocs-ext
  Running setup.py (path:/var/build/user_builds/kineticlib/envs/latest/build/readthedocs-ext/setup.py) egg_info for package readthedocs-ext

    warning: no files found matching '*.css' under directory 'readthedocs_ext'
Installing collected packages: readthedocs-ext
  Running setup.py install for readthedocs-ext

    warning: no files found matching '*.css' under directory 'readthedocs_ext'
Successfully installed readthedocs-ext
Cleaning up...


requirements
-----

Requirement already satisfied (use --upgrade to upgrade): numpydoc in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages (from -r docs/requirements.txt (line 1))
Requirement already satisfied (use --upgrade to upgrade): kineticlib in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages (from -r docs/requirements.txt (line 2))
Cleaning up...


install
-----

running install
running build
running build_py
creating build
creating build/lib
creating build/lib/kineticlib
copying src/kineticlib/wtpoly.py -> build/lib/kineticlib
copying src/kineticlib/ratesvibr.py -> build/lib/kineticlib
copying src/kineticlib/errors.py -> build/lib/kineticlib
copying src/kineticlib/probabilities.py -> build/lib/kineticlib
copying src/kineticlib/omegaint.py -> build/lib/kineticlib
copying src/kineticlib/__init__.py -> build/lib/kineticlib
copying src/kineticlib/loaddata.py -> build/lib/kineticlib
copying src/kineticlib/particles.py -> build/lib/kineticlib
copying src/kineticlib/ratesdiss.py -> build/lib/kineticlib
copying src/kineticlib/reltimes.py -> build/lib/kineticlib
copying src/kineticlib/affinities.py -> build/lib/kineticlib
copying src/kineticlib/crosssection.py -> build/lib/kineticlib
creating build/lib/kineticlib/data
creating build/lib/kineticlib/data/models
copying src/kineticlib/data/models/dissociation.csv -> build/lib/kineticlib/data/models
copying src/kineticlib/data/models/interactions.csv -> build/lib/kineticlib/data/models
creating build/lib/kineticlib/data/particles
copying src/kineticlib/data/particles/O2.dat -> build/lib/kineticlib/data/particles
copying src/kineticlib/data/particles/n2.dat -> build/lib/kineticlib/data/particles
copying src/kineticlib/data/particles/n.dat -> build/lib/kineticlib/data/particles
creating build/lib/kineticlib/data/spectra
copying src/kineticlib/data/spectra/n2.dat -> build/lib/kineticlib/data/spectra
running install_lib
copying build/lib/kineticlib/wtpoly.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/ratesvibr.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/errors.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/probabilities.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/omegaint.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/__init__.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/loaddata.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/particles.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/ratesdiss.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/data/spectra/n2.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/spectra
copying build/lib/kineticlib/data/particles/O2.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/particles
copying build/lib/kineticlib/data/particles/n2.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/particles
copying build/lib/kineticlib/data/particles/n.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/particles
copying build/lib/kineticlib/data/models/dissociation.csv -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/models
copying build/lib/kineticlib/data/models/interactions.csv -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/models
copying build/lib/kineticlib/reltimes.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/affinities.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/crosssection.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/wtpoly.py to wtpoly.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/ratesvibr.py to ratesvibr.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/errors.py to errors.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/probabilities.py to probabilities.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/omegaint.py to omegaint.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/__init__.py to __init__.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/loaddata.py to loaddata.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/particles.py to particles.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/ratesdiss.py to ratesdiss.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/reltimes.py to reltimes.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/affinities.py to affinities.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/crosssection.py to crosssection.cpython-34.pyc
running install_egg_info
Removing /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib-0.6.egg-info
Writing /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib-0.6.egg-info

Environment Standard Error



checkout
-----



venv
-----



sphinx
-----



requirements
-----



install
-----

/usr/lib/python3.4/distutils/dist.py:260: UserWarning: Unknown distribution option: 'include_package_data'
  warnings.warn(msg)

My conf.py has

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.mathjax',
    'sphinx.ext.autosummary',
    'numpydoc',
]
numpydoc_show_class_members = False

So, I have no idea why automodule is listed as an unknown directive.

Westwardly

Answer 1

This is the first FAQ...

My project isn’t building with autodoc First, you should check out the Builds tab of your project. That records all of the build attempts that RTD has made to build your project. If you see ImportError messages for custom Python modules, you should enable the virtualenv feature in the Admin page of your project, which will install your project into a virtualenv, and allow you to specify a requirements.txt file for your project.

emphasis mine..

Delicacy

I have that enabled already. Turns out, I had the wrong path to conf.py specified. – Westwardly

Answer 2

The other answers address the issue, but I thought I'd put together a summary for troubleshooting readthedocs+autodoc for other users with issues with autodoc commands (automodule, autoclass, autofunction) in RTD but not locally with make html —there are multiple Qs in SE with different issues. These can be resolved by:

• Inspect errors: In RTD Build page one can see the Errors that arose in view raw.
  • A common issue is missing modules or the target module.
• Browser hard refresh: In a browser it is critical to do a hard refresh of the pages (Shift+refresh button). Silly but I'd say 90% of issues come from this.
• enable autodoc sphinx.ext.autodoc needs to be in extension.

Notes

sys.path.insert(0, os.path.abspath("../../")) is really ugly. The same can be achieved in .readthedocs.yml with path: .. The yaml may look like this:

version: 2

build:
  os: ubuntu-20.04
  tools:
    python: "3.8"

sphinx:
   configuration: docs/source/conf.py
   builder: html
   fail_on_warning: false

python:
   install:
     - method: pip
       path: .
     - requirements: requirements.txt
     - requirements: docs/requirements.txt

Notes about the yaml:

• file:
  • If the name of the yaml file is wrong you'll get a suggestion in RTD to use one
  • If the file is incorrect the build will fail.
  • If the file is correct, nothing.
• Do specify python version
• build only html for now
• switch fail_on_warning for quicker troubleshooting —until the Sphinx5.0 deprecation warnings kick in

In the config.py, RTD will add readthedocs_ext.readthedocs it won't make a difference with make html locally —but it might in the future. sphinx_toolbox.more_autodoc might work best before sphinx.ext.autodoc:

extensions = [
    'readthedocs_ext.readthedocs',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx_toolbox.more_autodoc',
    'sphinx.ext.autodoc']

If you get a missing _static for html_static_path error change:

html_static_path = []

Changing the theme will help in the formatting fixes when running make html.

html_theme = 'sphinx_rtd_theme'

The extension sphinx_toolbox.more_autodoc.typehints does not make Sphinx behave as a type checker, so if there are modules imported for typehinting only (typing.TYPE_CHECKING == True), the code needs to also check if 'sphinx':

if typing.TYPE_CHECKING or 'sphinx' in sys.modules:
    from foo import Foo

def to_foo(self) -> Foo:
    ...

Velocipede

just one important thing to mention here @matteo-ferla is you have to rename '.readthedocs.yaml' into '.readthedocs.yml' otherwise it will not be picked. – Diacid

Ah, yes —Thanks (fixed typo). Classic blunder. Second only to config and conf mixup. – Velocipede