Python Sphinx autodoc 未在 readthedocs 上呈现

如何解决Python Sphinx autodoc 未在 readthedocs 上呈现

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

例如，这是参考指南的第一部分在我本地渲染时的样子：

但是，当文档在 readthedocs (see here) 上呈现时，参考指南不包含提取的文档；只是在 .rst 文件中找到的标题。

预期行为

我希望 readthedocs 上呈现的文档与本地呈现的文档相同。然而，这并没有发生。

通过查看 here，我已确认当前版本的文档中 readthedocs 上显示的版本。

但是当我尝试下载文档的 PDF 或 HTML 版本时，参考指南不包含文档字符串。

其他信息

根据 readthedocs documentation，本地构建不应推送到 GitHub；只有源文件。

这与 this issue 有点相关，但我无法使建议的解决方案起作用。

更新我遵循了 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 上。

解决方法

您的项目的依赖项未在 RTD 上指定，但您已在本地安装了这些依赖项。您可以在 build log 中验证这一点。访问您的项目的构建，点击构建，然后点击“查看原始数据”。

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)

要纠正这种情况，您必须指定必须安装项目的依赖项。见Specifying Dependencies。

您必须：

创建一个pip requirements file that specifies requirements，或
创建一个指定 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},

您已在此文件中定义了项目要求，然后您必须配置阅读文档以识别此文件以安装依赖项。首选方法是使用 configuration file，但您也可以通过 project's Admin Dashboard 执行此操作。

我遇到了完全相同的问题。 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")