我构建了 Sphinx 文档，并且该构建在本地运行良好。我的文档字符串如下所示。
当移动到 readthedoc.io 时，我在下面添加了一个特定的要求文件docs/requirement.txt这是：
sphinx==3.5.4
sphinx_rtd_theme==0.5.2
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4
And my .readthedocs.yaml好像：
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# Optionally build your docs in additional formats such as PDF
formats:
- pdf
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: docs/requirements.txt
However, when building the doc on readthedocs.io, even if my build completes with no error, the docstrings don't show.
这是日志：
git clone --no-single-branch --depth 50 https://github.com/Green-Investement-Dashboard/GRID_app.git .
git checkout --force origin/app_v2
git clean -d -f -f
python3.7 -mvirtualenv /home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --upgrade --no-cache-dir pip setuptools
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --upgrade --no-cache-dir mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme readthedocs-sphinx-ext<2.2
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --exists-action=w --no-cache-dir -r docs/requirements.txt
cat docs/source/conf.py
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m sphinx -b latex -D language=en -d _build/doctrees . _build/latex
cat latexmkrc
latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=grid-app -interaction=nonstopmode
mv -f /home/docs/checkouts/readthedocs.org/user_builds/grid-app/checkouts/latest/docs/source/_build/latex/grid-app.pdf /home/docs/checkouts/readthedocs.org/user_builds/grid-app/artifacts/latest/sphinx_pdf/grid-app.pdf
我做错了什么？
还记得斯芬克斯的Autodoc扩展“导入要记录的模块”。这是因为 Autodoc 使用 Python 自省来访问文档字符串。从 Autodoc 的角度来看，这样做的优点是可以让 Python 进行解析。从用户的角度来看，缺点是我们必须确保所有依赖项都已安装，或者至少是“模拟”。
这在您的开发计算机上不是问题，当然，您的包所依赖的所有外部库都已经安装。但是，当在 Read-the-Docs 服务器上构建时，可以说是在“裸”Python 环境中，其中许多都丢失了。您添加了构建 Sphinx 项目所需的依赖项docs/requirements.txt，如果您不使用 Autodoc 扩展，这就足够了。但既然你这样做了，你的文档字符串就会丢失，因为你的包中的模块导入了类似的东西flask_login or plotly。在“阅读文档”中，如果您查看扩展日志（而不是您发布的基本日志），您应该会看到相应的警告消息，可以通过单击“构建”选项卡中的“查看原始日志”来访问该日志。这些是警告，而不是错误。所以构建通过了，但是文档字符串丢失了。
添加额外的依赖项会减慢文档构建速度，因为它们都必须在 Sphinx 开始工作之前安装。所以更好的策略是嘲笑他们。您可以首先在新的虚拟环境中进行本地测试。
导入的包如下import numpy可以通过添加 Autodoc 选项来模拟autodoc_mock_imports to conf.py:
autodoc_mock_imports = ['numpy']
如果您直接从包的名称空间导入对象，例如from numpy import array，可能需要使用MagicMock来自unittest模块代替：
from unittest.mock import MagicMock
sys.modules['numpy'] = MagicMock()