有没有办法在 Sphinx 中预构建 autodoc 生成的 .rst 文件答案

【问题标题】：Is there a way to prebuild the .rst files generated by autodoc in Sphinx有没有办法在 Sphinx 中预构建 autodoc 生成的 .rst 文件
【发布时间】：2015-03-10 22:26:41
【问题描述】：

我有一个项目，我为该项目构建了一组带有sphinx.ext.apidoc 的 .rst 文件，用于从项目的文档字符串中提取文档。

这些文件如下所示：

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

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

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

make html 在我的计算机上正确构建文档，但需要我编辑 conf.py 文件以将我的项目添加到 python 系统路径，以便在 autodoc 尝试时正确找到 .rst 文件中提到的模块导入它们。

但是，当我尝试在 readthedocs 上构建文档时，autodoc 无法找到引用的模块，因为我不知道需要将什么路径添加到 python 系统路径才能让 autodoc 正确找到项目模块.

我想知道是否可以在本地环境中使用 autodoc 预先构建 .rst 文件，以便它们不再包含对 autodoc 的任何调用，然后将它们上传到 readthedocs，这样就没有需要在那里运行 autodoc 扩展。

如果没有办法做到这一点，解决该问题的正确方法是什么？

【问题讨论】：

您没有setup.py 告诉RTD 等如何安装项目吗？
您找到解决此问题的方法了吗？我有一个基于 cython 的项目，所以（我猜）不可能在 RTD 上构建。
是的，当时我最终写了一篇关于它的博客文章：andreikucharavy.com/L3Cache/parsing-sphinx 我将在下面更新答案。主要思想是使用这里建议的模拟模块：docs.readthedocs.org/en/latest/faq.html

标签： python python-sphinx autodoc read-the-docs

【解决方案1】：

经过一番修改，readthedocs FAQ 提供了解决方案：为了在 venv readthedoc 构建中依赖 C 并且无法通过 pip 轻松安装的模块，有必要模拟它们并您在文档的myproject/docs/source 目录（或Sphinx 的conf.py 所在的任何位置）内的conf.py 文件中导入的所有子模块。在我的情况下，代码如下：

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()})

【讨论】：