Python Sphinx autodoc 未在 readthedocs 上呈现
Python Sphinx autodoc not rendering on readthedocs
我在 Github 上托管了一个名为 spike2py. I have prepared my docs using Sphinx and .rst files. These files are hosted on GitHub here. I am able to successfully run make html locally and obtain the desired output. That is, the Reference Guide part of the documentation contains the API automatically generated using the docstring I have included in my code, and referenced using calls to autoclass and autofunction (reference_guide.rst) 的 Python 包。
例如，这是参考指南的第一部分在本地呈现时的样子：
然而，当文档在 readthedocs (see here) 上呈现时，参考指南不包含提取的文档；只是在 .rst 文件中找到的 headers。
预期行为
我希望在 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 and 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, but you can also do this through the 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")
我在 Github 上托管了一个名为 spike2py. I have prepared my docs using Sphinx and .rst files. These files are hosted on GitHub here. I am able to successfully run make html locally and obtain the desired output. That is, the Reference Guide part of the documentation contains the API automatically generated using the docstring I have included in my code, and referenced using calls to autoclass and autofunction (reference_guide.rst) 的 Python 包。
例如，这是参考指南的第一部分在本地呈现时的样子：
然而，当文档在 readthedocs (see here) 上呈现时，参考指南不包含提取的文档；只是在 .rst 文件中找到的 headers。
预期行为
我希望在 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.pydocs_requires节中。请参阅 Pyramid 存储库中的示例及其 rtd.txt and 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, but you can also do this through the 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")