Python Sphinx autodoc 未在 readthedocs 上呈现

Question

我有一个托管在 Github 上的 Python 包，名为Spike2py。我已经使用 Sphinx 和 .rst 文件准备了我的文档。这些文件托管在 GitHub上。我能够make html在本地成功运行并获得所需的输出。也就是说，文档的参考指南部分包含使用我包含在代码中的文档字符串自动生成的 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 的类型提示，我必须在文件中指定 Python 的版本.readthedocs.yml。

然后我被 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 上。

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]

安装程序.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},

如果您已在此文件中定义了项目要求，则必须配置“阅读文档”以识别此文件以安装依赖项。首选方法是使用配置文件，但您也可以通过项目的管理仪表板来执行此操作。