在ReadtheDocs上未呈现Python Sphinx自动文档 [英] Python Sphinx autodoc not rendering on readthedocs

问题描述

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

例如，当我在本地呈现《参考指南》的第一部分时，它是这样的：

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

预期行为

我希望在ReadtheDocs上呈现的文档与本地呈现的文档相同。但是，这并未发生。

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

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

其他信息

根据Readthedocsdocumentation，不应将本地版本推送到GitHub；只应将源文件推送到GitHub。

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

更新 我遵循了Steve Piercy推荐的解决方案，这解决了部分问题。我添加了docs/requirements.txt文件和.readthedocs.yml文件。

接下来，我注意到构建使用的是Python3.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。

您必须：

1. 创建pip requirements file that specifies requirements或
2. 创建一个指定pip install选项的文件，该选项将安装已经在其他地方定义的需求，例如在setup.pydocs_requires节中。请参阅金字塔存储库中包含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以识别此文件以安装依赖项。首选方法是使用configuration file，但也可以通过project's Admin Dashboard执行此操作。

这篇关于在ReadtheDocs上未呈现Python Sphinx自动文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！