Python Sphinx自动文档在Readthedocs上无法渲染

Question

我在Github上有一个名为spike2py的Python包。我使用Sphinx和.rst文件准备了我的文档，这些文件托管在GitHub 这里。我能够成功地在本地运行make html并获得所需的输出。也就是说，文档的参考指南部分包含了使用我在代码中包含的docstring自动生成的API，并使用autoclass和autofunction（reference_guide.rst）进行引用。

例如，以下是我本地呈现的参考指南的前一部分：

然而，当文档在readthedocs上呈现时（请见此处），参考指南不包含提取的文档字符串，只有在.rst文件中找到的标题。 期望的行为 我期望在readthedocs上呈现的文档与本地呈现的文档相同。然而，这种情况并未发生。

通过查看此处，我确认正在readthedocs上呈现的版本是我的文档的当前版本。

但是，当我尝试下载文档的PDF或HTML版本时，参考指南不包括文档字符串。 其他信息 根据readthedocs 文档，本地构建不应推送到GitHub；只需推送源文件。

这与这个问题有些相关，但我无法使建议的解决方案起作用。

更新 我按照Steve Piercy建议的解决方案做了，这解决了部分问题。我添加了一个docs/requirements.txt文件和一个.readthedocs.yml文件。

接下来我注意到构建正在使用Python 3.7.9。鉴于我使用的是Python >= 3.8的类型提示，我必须在.readthedocs.yml文件中指定Python的版本。

然后我卡在了RTD构建告诉我找不到我的index.rst文件上。

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/application.py", line 348, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 297, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 311, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 421, in read
    raise SphinxError('master file %s not found' %
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found

但是我通过在我的.readthedocs.yml中指定以下内容来解决了这个问题:

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/source/conf.py

在此修复之后，文档构建时似乎没有出现错误，并包括以下内容：

generating indices...  genindex py-modindexdone
highlighting module code... [ 20%] spike2py.channels
highlighting module code... [ 40%] spike2py.plot
highlighting module code... [ 60%] spike2py.read
highlighting module code... [ 80%] spike2py.sig_proc
highlighting module code... [100%] spike2py.trial

是的，文档字符串出现在 RTD 上了。

- Martin Héroux

---

这个答案提供了一些关于RTD上构建的情况的见解，尽管那个线程中的OP使用了一个更复杂的设置。无论如何，如果autodoc在本地和GitHub上构建但在RTD上没有构建，那么很可能是因为RTD构建无法导入您的模块（我在该网站上经验不足以确定解决方案，但这是您应该搜索的逻辑 - 我希望更有经验的成员能够贡献他们对问题的分析。） - bad_coder

Answer 1

您项目的依赖项未在RTD中指定，但您已在本地安装了依赖项。 您可以在构建日志中验证此信息。 访问您项目的构建界面，选择一个构建，并单击“查看原始内容”。

WARNING: autodoc: failed to import class 'trial.TrialInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'trial.Trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'trial.load' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.ChannelInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Event' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Keyboard' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Waveform' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Wavemark' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'sig_proc.SignalProcessing' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'read.read' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)

为解决这个问题，您必须指定安装项目的依赖项。请参见指定依赖项。

您可以选择：

1. 创建一个pip需求文件来指定要安装的依赖包
2. 创建一个文件，指定pip install选项，该选项将安装已在其他位置定义的依赖关系，例如在setup.py的docs_requires部分。请参见Pyramid存储库中的示例：rtd.txt 和 setup.py

rtd.txt

-e .[docs]

setup.py

docs_extras = [
    'Sphinx >= 3.0.0',  # Force RTD to use >= 3.0.0
    'docutils',
    'pylons-sphinx-themes >= 1.0.8',  # Ethical Ads
    'pylons_sphinx_latesturl',
    'repoze.sphinx.autointerface',
    'sphinxcontrib-autoprogram',
]
# ...
    extras_require={'testing': testing_extras, 'docs': docs_extras},

当你在此文件中定义了项目需求后，你必须配置Read the Docs以识别此文件并安装依赖。首选方法是使用配置文件，但你也可以通过项目的管理仪表板来完成这个过程。

- Steve Piercy

---

感谢您关注这个问题，史蒂夫。您的建议让我解决了大部分问题。然而，正如您在上面的更新中所看到的，我仍然遇到了一些问题。 - Martin Héroux

@MartinHéroux 我刚刚检查了构建的文档，发现最新版本中有文档字符串。还有问题吗？ - Steve Piercy

现在一切似乎都正常了！太好了，谢谢。我想我没有检查最新的编译版本...道歉，并感谢您的帮助。 - Martin Héroux

Answer 2

我有完全相同的问题。Readthedocs无法从我的项目中提取文档字符串，因为它没有找到我的项目模块。

我通过在docs/conf.py中添加2个相对路径来解决这个问题：

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

现在，docs/conf.py 的顶部如下所示：

import os
import sys
import sphinx_rtd_theme

    # If extensions (or modules to document with autodoc) are in another directory,
    # add these directories to sys.path here. If the directory is relative to the
    # documentation root, use os.path.abspath to make it absolute, like shown here.
    sys.path.insert(0, os.path.abspath("."))
    sys.path.insert(0, os.path.abspath("../"))
    sys.path.insert(1, os.path.dirname(os.path.abspath("../")) + os.sep + "feature_engine")

- Sole Galli

---

感谢您关注此问题。不幸的是，这并没有解决我的问题。我已经在conf.py文件中指定了模块的路径；如果没有指定，我就无法在自己的机器上本地构建文档。当我指定它时，我可以本地构建文档。问题是RTD不能呈现docstrings。另外，为什么要导入sphinx_rtd_theme？如果在conf.py中没有使用它。你建议答案中的第三个sys.path行是做什么用的？再次感谢您关注此问题。 - Martin Héroux