Search code examples
pythongitdocumentationmockingdocumentation-generation

How can I set up Read the Docs so the Sphinx autodoc option works?

My project isn't building with autodoc. I'm running into this frequently asked question about my project not building in autodoc. But, some of dependencies include c code which won't execute on Build the Docs servers. So I read the approach in this blog explaining that I should use mock. This relates to the stackoverflow question 'how-to-mock-so-that-from-x-import-works'.

In the advanced settings section of the admin page on Read the Docs, there's an option to use virtualenv, which I checked, and then the path to the root of my project to requirements.txt is requested.

The project directory is structured as:

GatherNews/
    requirements.txt

When I use GatherNews/requirements.txt as the path. I get the error:

/var/build/user_builds/gathernews/checkouts/latest/docs/api/grss.rst:10: WARNING: autodoc: failed to import class u'CaptureFeeds' from module u'gathernews.gRSS'; the following exception was raised:

Traceback (most recent call last):

File "/home/docs/checkouts/readthedocs.org/user_builds/gathernews/envs/latest/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object import(self.modname)

File "/home/docs/checkouts/readthedocs.org/user_builds/gathernews/envs/latest/local/lib/python2.7/site-packages/gathernews/init.py", line 1, in import gRSS

File "/home/docs/checkouts/readthedocs.org/user_builds/gathernews/envs/latest/local/lib/python2.7/site-packages/gathernews/gRSS.py", line 38, in import feedparser

ImportError: No module named feedparser /var/build/user_builds/gathernews/checkouts/latest/docs/_themes/README.rst:: WARNING: document isn't included in any toctree

My question is how do I tie this all together? Specifically, am I using the correct path to my requirements.txt for Read the Docs to build successfully? If my path to my requirements.txt is correct, then how can I include the mock package to successfully generate autodocs?

Solution

  • I created a fork of https://github.com/Bonza-Times/GatherNews and set of a ReadTheDocs build for it. The only issue seems to be that you used the wrong path to requirements.txt. It says

    Path from the root of your project.

    so that does not include GatherNews. Just use requirements.txt as the path, since that file is in the top level of your git repository.

    Since you've got Use virtualenv checked, ReadTheDocs should automatically take care of making sure the virtualenv's site-packages are available in sys.path to the sphinx-build script.

    I don't see any need for mocking modules, since feedparser doesn't have any hard dependencies on C libraries. It can be built against libxml2, but it doesn't have to.

    With the path to requirements.txt fixed I was able to do a successful build.

    These are the "Advanced Settings" I used, the remaining settings are at default values:

    Advanced settings