Python的Sphinx自动文档生成工具在ReadTheDocs上无法显示任何内容。

Question

我有一个Python包，链接如下：https://github.com/neuropsychology/Neuropsydia.py 我想使用Sphinx自动记录它。我在每个函数和类中添加了文档字符串。

我在ReadTheDocs上注册了一个账号，并进行了相应的设置（即带有conf.py文件的docs/目录）。然后基本上我尝试了所有可能性：每一种autodoc::，autofunction::，autoclass::的组合；我尝试使用与其他已经记录API的包相同的conf.py文件（当然，根据我的情况进行了特定的更改）；但就是不行，API页面仍然是空的...

- Dominique Makowski

---

如果您前往RTD的构建页面（https://readthedocs.org/projects/<your-project>/builds/），是否有任何反馈？您是如何生成 api.rst 的？我发现这对于初始设置非常有用：https://jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/ - jonrsharpe

谢谢您提供这个非常有用的链接！然而，尽管我尝试重现这些步骤并尝试从头开始构建文档，但仍然没有显示任何内容。最糟糕的是，当我运行makefile（使用命令make html）时，它没有显示任何特定的错误和与我正在尝试记录的包无关的内容...我就是想不明白为什么！至于我的api.rst文件，它只是通过创建rst文档并插入一些..autoclass::指令来生成的。无论如何，感谢您的回答！ - Dominique Makowski

那可能是问题所在，你考虑过使用Sphinx来生成文档而不是自己试图去做吗？ - jonrsharpe

Answer 1

尝试将以下内容添加到您的conf.py文件中：

：

########### TRICK FOUND ON SOME TUTORIAL : ADD IN THE MOCK_MODULES ANY EXTERNAL MODULE YOU'RE USING IN YOUR PACKAGE.

import mock

MOCK_MODULES = ['numpy', 'scipy', 'sklearn', 'matplotlib', 'matplotlib.pyplot', 'scipy.interpolate', 'scipy.special', 'math', '__future__', 'toolboxutilities']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

在 MOCK_MODULES 中，添加任何你的项目使用的单个外部导入。我曾经遇到完全相同的问题，这解决了它。

另外，在 conf.py 中，不要忘记添加 ： 。

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

在您的情况下，您已经拥有它，但我提到它是为了防止其他遇到相同问题的人看到我的答案。

- Guillaume