Is there a way to prebuild the .rst files generated by autodoc in Sphinx

Question

I have a project for which I've build a set of .rst files with sphinx.ext.apidoc that extracts documentation from my project's docstrings.

Those files look like the following:

Submodules
----------
.. toctree::
   mymodule.submodule

Module contents
---------------

.. automodule:: mymodule
   :members:
   :undoc-members:
   :show-inheritance:

make html builds the documentation properly on my computer, but requires me to edit the conf.py file to add my project to the python system path, so that it finds properly the modules mentioned in the .rst files when autodoc tries to import them.

However, when I try to build the documentation on the readthedocs, autodoc is unable to find the referenced modules because I don't know what path needs to be added to the python system path for the autodoc to properly find the project modules.

I was wondering if it would be possible to pre-build the .rst files with autodoc in the local environment, so that they don't contain any calls to autodoc anymore and then upload them to readthedocs, so that there is no need to run the autodoc extension there.

If there is no way to do this, what would be the proper way of solving that problem?

Answer 1

After some tinkering, the solution was provided by the readthedocs FAQ : In order for the modules that depend on C and cannot be easily installed by pip inside the venv readthedoc builds, it is necessary to mock them and all sub-modules you import in the conf.py file within the myproject/docs/source directory of your documentation (or wherever your Sphinx's conf.py is). in my case the code was the following:

if on_rtd:
    warn('debug -syspath -edit: %s'%os.path.abspath('../..'))
    sys.path.insert(0, os.path.abspath('../..'))

    class Mock(MagicMock):

        @classmethod
        def __getattr__(cls, name):
            return Mock()

        @classmethod
        def __getitem__(cls, name):
            return Mock()


    MOCK_MODULES = ['numpy',
                    'scikit-learn',
                    'pymongo',
                    'cython',
                    'Cython',
                    'matplotlib',
                    'matplotlib.pyplot',
                    'scipy',
                    'scipy.stats',
                    'scipy.sparse',
                    'scipy.sparse.linalg',
                    'scipy.sparse.csgraph',
                    'scikits',
                    'scikits.sparse',
                    'scikits.sparse.cholmod',
                    'sklearn',
                    'sklearn.cluster',
                    'python-Levenshtein'
                    'levenstein',
                    'python.levenstein'
                    ]

    for mod_name in MOCK_MODULES:
        sys.modules.update({mod_name: Mock()})