Read The Docs 与 automodule 不兼容
我为我的项目写了一些文档（在Python的文档字符串里），并在我本地的电脑上用Sphinx测试了一切——一切都正常，所有的导入都工作得很好。
于是我在Read The Docs上设置了一个自定义环境（Python 3、numpydoc和我的库），把docs目录（还有docs/source子目录）添加到了我的Github仓库里，Read The Docs上的构建也通过了，但什么都没有生成（查看文档的链接只显示了一个Nginx 404页面）。
日志内容如下：
State: Finished
Outcome: Passed
Version: latest
Type: html
Sphinx Standard Output
html
-----
Making output directory...
Running Sphinx v1.2.2
loading translations [en]... done
building [readthedocs]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [ 20%] contents
reading sources... [ 40%] source/contents
reading sources... [ 60%] source/index
reading sources... [ 80%] source/kineticlib
reading sources... [100%] source/modules
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 20%] contents
writing output... [ 40%] source/contents
writing output... [ 60%] source/index
writing output... [ 80%] source/kineticlib
writing output... [100%] source/modules
writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 15 warnings.
Copying readthedocs-ext.js_t... done
Sphinx Standard Error
html
-----
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:11: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.affinities
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:19: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.crosssection
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:27: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.errors
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:35: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.loaddata
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:43: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.omegaint
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:51: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.particles
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:59: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.probabilities
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:67: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.ratesdiss
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:75: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.ratesvibr
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:83: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.reltimes
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/kineticlib.rst:91: ERROR: Unknown directive type "automodule".
.. automodule:: kineticlib.wtpoly
:members:
:undoc-members:
:show-inheritance:
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/contents.rst:: WARNING: document isn't included in any toctree
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/index.rst:: WARNING: document isn't included in any toctree
/var/build/user_builds/kineticlib/checkouts/latest/docs/source/modules.rst:: WARNING: document isn't included in any toctree
WARNING: html_static_path entry '/var/build/user_builds/kineticlib/checkouts/latest/docs/_static' does not exist
Setup Output
checkout
-----
venv
-----
Using base prefix '/usr'
New python executable in /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/bin/python3
Not overwriting existing python script /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/bin/python (you must use /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/bin/python3)
Installing setuptools, pip...done.
Running virtualenv with interpreter /usr/bin/python3
sphinx
-----
Requirement already up-to-date: sphinx==1.2.2 in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages
Requirement already up-to-date: virtualenv==1.9.1 in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages
Requirement already up-to-date: docutils==0.11 in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages
Downloading/unpacking readthedocs-ext from git+git://github.com/ericholscher/readthedocs-sphinx-ext
Cloning git://github.com/ericholscher/readthedocs-sphinx-ext to /var/build/user_builds/kineticlib/envs/latest/build/readthedocs-ext
Running setup.py (path:/var/build/user_builds/kineticlib/envs/latest/build/readthedocs-ext/setup.py) egg_info for package readthedocs-ext
warning: no files found matching '*.css' under directory 'readthedocs_ext'
Installing collected packages: readthedocs-ext
Running setup.py install for readthedocs-ext
warning: no files found matching '*.css' under directory 'readthedocs_ext'
Successfully installed readthedocs-ext
Cleaning up...
requirements
-----
Requirement already satisfied (use --upgrade to upgrade): numpydoc in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages (from -r docs/requirements.txt (line 1))
Requirement already satisfied (use --upgrade to upgrade): kineticlib in /var/build/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages (from -r docs/requirements.txt (line 2))
Cleaning up...
install
-----
running install
running build
running build_py
creating build
creating build/lib
creating build/lib/kineticlib
copying src/kineticlib/wtpoly.py -> build/lib/kineticlib
copying src/kineticlib/ratesvibr.py -> build/lib/kineticlib
copying src/kineticlib/errors.py -> build/lib/kineticlib
copying src/kineticlib/probabilities.py -> build/lib/kineticlib
copying src/kineticlib/omegaint.py -> build/lib/kineticlib
copying src/kineticlib/__init__.py -> build/lib/kineticlib
copying src/kineticlib/loaddata.py -> build/lib/kineticlib
copying src/kineticlib/particles.py -> build/lib/kineticlib
copying src/kineticlib/ratesdiss.py -> build/lib/kineticlib
copying src/kineticlib/reltimes.py -> build/lib/kineticlib
copying src/kineticlib/affinities.py -> build/lib/kineticlib
copying src/kineticlib/crosssection.py -> build/lib/kineticlib
creating build/lib/kineticlib/data
creating build/lib/kineticlib/data/models
copying src/kineticlib/data/models/dissociation.csv -> build/lib/kineticlib/data/models
copying src/kineticlib/data/models/interactions.csv -> build/lib/kineticlib/data/models
creating build/lib/kineticlib/data/particles
copying src/kineticlib/data/particles/O2.dat -> build/lib/kineticlib/data/particles
copying src/kineticlib/data/particles/n2.dat -> build/lib/kineticlib/data/particles
copying src/kineticlib/data/particles/n.dat -> build/lib/kineticlib/data/particles
creating build/lib/kineticlib/data/spectra
copying src/kineticlib/data/spectra/n2.dat -> build/lib/kineticlib/data/spectra
running install_lib
copying build/lib/kineticlib/wtpoly.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/ratesvibr.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/errors.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/probabilities.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/omegaint.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/__init__.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/loaddata.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/particles.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/ratesdiss.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/data/spectra/n2.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/spectra
copying build/lib/kineticlib/data/particles/O2.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/particles
copying build/lib/kineticlib/data/particles/n2.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/particles
copying build/lib/kineticlib/data/particles/n.dat -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/particles
copying build/lib/kineticlib/data/models/dissociation.csv -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/models
copying build/lib/kineticlib/data/models/interactions.csv -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/data/models
copying build/lib/kineticlib/reltimes.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/affinities.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
copying build/lib/kineticlib/crosssection.py -> /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/wtpoly.py to wtpoly.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/ratesvibr.py to ratesvibr.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/errors.py to errors.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/probabilities.py to probabilities.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/omegaint.py to omegaint.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/__init__.py to __init__.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/loaddata.py to loaddata.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/particles.py to particles.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/ratesdiss.py to ratesdiss.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/reltimes.py to reltimes.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/affinities.py to affinities.cpython-34.pyc
byte-compiling /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib/crosssection.py to crosssection.cpython-34.pyc
running install_egg_info
Removing /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib-0.6.egg-info
Writing /home/docs/checkouts/readthedocs.org/user_builds/kineticlib/envs/latest/lib/python3.4/site-packages/kineticlib-0.6.egg-info
Environment Standard Error
checkout
-----
venv
-----
sphinx
-----
requirements
-----
install
-----
/usr/lib/python3.4/distutils/dist.py:260: UserWarning: Unknown distribution option: 'include_package_data'
warnings.warn(msg)
我的conf.py文件里有
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.mathjax',
'sphinx.ext.autosummary',
'numpydoc',
]
numpydoc_show_class_members = False
所以，我不知道为什么automodule会被列为一个未知的指令。
2 个回答
2
其他回答已经解决了这个问题，但我想为遇到autodoc命令（如automodule、autoclass、autofunction）在RTD（Read the Docs）上有问题的用户整理一个故障排除的总结。可能在本地使用make html时没有问题——在Stack Exchange上有很多不同的问题。以下是一些解决方法：
- 检查错误：在RTD的构建页面，可以查看
view raw中出现的错误。- 一个常见的问题是缺少模块或目标模块。
- 浏览器强制刷新：在浏览器中，强制刷新页面（按Shift+刷新按钮）是非常重要的。虽然听起来简单，但我认为90%的问题都是由此引起的。
- 启用autodoc：需要在
extension中添加sphinx.ext.autodoc。
注意事项
sys.path.insert(0, os.path.abspath("../../"))看起来很丑陋。可以在.readthedocs.yml中用path: .来实现。yaml文件可能看起来像这样：
version: 2
build:
os: ubuntu-20.04
tools:
python: "3.8"
sphinx:
configuration: docs/source/conf.py
builder: html
fail_on_warning: false
python:
install:
- method: pip
path: .
- requirements: requirements.txt
- requirements: docs/requirements.txt
关于yaml的注意事项：
- 文件：
- 如果yaml文件的名称错误，RTD会建议你使用一个正确的文件。
- 如果文件不正确，构建将会失败。
- 如果文件正确，则不会有任何提示。
- 一定要指定Python版本。
- 目前只构建html。
- 将
fail_on_warning切换为更快的故障排除——直到Sphinx 5.0的弃用警告出现。
在config.py中，RTD会添加readthedocs_ext.readthedocs，这在本地使用make html时不会有区别——但将来可能会有影响。sphinx_toolbox.more_autodoc在sphinx.ext.autodoc之前使用效果可能更好：
extensions = [
'readthedocs_ext.readthedocs',
'sphinx.ext.viewcode',
'sphinx.ext.todo',
'sphinx_toolbox.more_autodoc',
'sphinx.ext.autodoc']
如果你遇到html_static_path缺少_static的错误，可以更改：
html_static_path = []
更改主题将有助于在运行make html时修复格式问题。
html_theme = 'sphinx_rtd_theme'
扩展sphinx_toolbox.more_autodoc.typehints并不会让Sphinx变成类型检查器，所以如果有模块仅用于类型提示（typing.TYPE_CHECKING == True），代码还需要检查是否有'sphinx'：
if typing.TYPE_CHECKING or 'sphinx' in sys.modules:
from foo import Foo
def to_foo(self) -> Foo:
...
6
这是第一个常见问题解答...
我的项目无法通过自动文档生成来构建。首先，你应该查看你项目的构建标签。这个标签记录了RTD（Read the Docs）为你的项目尝试构建的所有记录。如果你看到关于自定义Python模块的导入错误信息，你应该在你项目的管理页面启用虚拟环境功能，这样可以把你的项目安装到一个虚拟环境中，并允许你为你的项目指定一个requirements.txt文件。
强调是我自己的观点..