ReadTheDocs not parsing docstrings in Python modules (Sphinx)

5
votes

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.

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.

1
python-sphinxread-the-docs
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. - Brad Baskin
Thanks @BradBaskin. See the fix below. - Arran Schlosberg

1 Answers

4
votes

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.