ReadTheDocs not parsing docstrings in Python modules (Sphinx)

Question

I have open-sourced some of my code, but the documentation won't build properly on ReadTheDocs despite working as expected with the Makefile created by sphinx-quickstart and make html locally. Can anyone please advise as to what I'm doing wrong with the RTD integration?

I have read about possibly building the module in a virtualenv with the RTD advanced settings but that doesn't work because I have scipy as a requirement and builds fail due to no BLAS library being available (it is also an unnecessarily long task for every build of docs).

sphinx.ext.autodoc and sphinx.ext.napoleon (for Google-style docstrings) are both included. Locally I just ran dev-scripts/api-docs.sh once which created docs/source/bnol.rst and docs/source/modules.rst. Then the standard Makefile (ignored in the git repo) is used to build docs as expected.

• GitHub repository with package in /bnol/
• Sphinx conf.py
• RTD-hosted docs not built properly

EDIT: I found this FAQ detailing the build process on RTD and used the same process with sphinx-build locally and it works as expected. I am trawling RTD logs for errors but nothing of note just yet.

Signboard

Hey @Arran Im no expert on RTD but it looks like you need the Makefile in the BNoL/docs folder in your github repo. I cannot see your github settings either but you also need the RTD service hook setup enabled. It should work once you have both of these. – Southwesterly

Thanks @BradBaskin. See the fix below. – Signboard

Answer 1

Usage of Sphinx's autodoc to create documentation from docstring comments requires that Python files be loaded and hence all of the modules that they import will so too be imported. ReadTheDocs will build required modules which, particularly in the case of numpy and scipy, may fail.

I corrected the problem by removing the modules from setup.py and instead listing them in a pip requirements file ./requirements.txt in the root of the package for use in actual package installation. A dummy (empty) requirements file was then placed in ./docs/source/ and ReadTheDocs configuration was pointed there (it appeared to automatically load ./requirements.txt even if not specified, hence the need for the dummy).

This still leaves the problem of importing modules which was fixed with mock as seen in my ./docs/source/conf.py file and detailed at: http://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-scipy/

A full list of changes can be seen in the commit that solved the problem.

Signboard

This helped me solve my problem, but I found that you don't have to remove the modules from setup.py and can just create the mock requirements file and point RTD to it. Cheers for posting the solution to your own problem. – Quyenr

I had the same problem; in my repo_dir/docs/conf.py I had set sys.path.insert(0, os.path.abspath('../app_dir')) corresponding to repo_dir/app_dir/__init__.py. Fixed it by changing it to sys.path.insert(0, os.path.abspath('../')) – Balladeer

Answer 2

1. First you need to make sure you are loading the package path properly in conf.py. Note the error message.

   sys.path.insert(0, os.path.abspath('../..')) sys.path.insert(0, os.path.abspath('../ExceptNotifier/init.py'))

2. If you are looking at the package path correctly, check that all packages related to shpinx are properly installed in requirments.txt. Also, keep in mind that args and dependency packages are different for each theme.

   extensions = [ 'sphinx.ext.autodoc','sphinx.ext.todo' ]

3. Sphinx validates the packages once. Concentrate on errors that must be compiled.

4. In my case, all modules with the same docstring were not exposed. All docstrings must not be the same. Change this if copy pasting made the dostrings the same.

5. When document is worked in local resources only. Check this stackoverflow:Docstrings are not included in Read the Docs Sphinx build

Craggy