Readthedocs.org: 允许 `pip install --no-deps` 满足 Sphinx autodoc 的依赖

创建于 2019-03-20 · 3评论 · 资料来源: readthedocs/readthedocs.org

细节

阅读 Docs 项目 URL： https :
构建 URL（如果适用）： https :
阅读文档用户名（如果适用）：zhuangjw

问题

我正在使用Sphinx-autodoc为我的 Python 包生成 API 文档。

最初我使用 Conda 来安装 readthedocs 上的完整依赖项，但构建时间太长，有时甚至失败（#4695）。所以，我切换到纯pip （https://github.com/JiaweiZhuang/xESMF/commit/53816d397b3c8f27b195132b27dbb41847e34e0f），这大大加快了构建速度。但是，自从那次切换之后，Sphinx-autodoc 无法生成 API 文档。我的API 页面几乎是空白的：

Screen Shot 2019-03-20 at 2 51 31 PM

这是因为我的包本身具有无法由pip安装的严重依赖项。某些 C/Fortran 扩展必须由conda 。所以，autodoc 不能导入我的包：

WARNING: autodoc: failed to import module 'xesmf.frontend'; the following exception was raised:
No module named 'xesmf'
WARNING: autodoc: failed to import module 'xesmf.backend'; the following exception was raised:
No module named 'xesmf'
...

我尝试过的方法

我能够使用 pip在本地生成正确的 API 文档，使用两个技巧：

通过pip install --no-deps xesmf强制安装我的包。
通过在conf.py添加autodoc_mock_imports = ['numpy', 'xarray', 'scipy', 'ESMF']来模拟导入依赖项。其中， ESMF是一个极其重的依赖，只能通过 Conda 安装（并且需要很长时间才能安装）。

即使使用autodoc_mock_imports ，我仍然需要 pip 安装我的包xesmf以提供 sphinx-autodoc 的文档字符串。我已阅读阅读文档配置文件，但找不到指定--no-deps选项或添加自定义 pip 命令的方法。

目前，我只能想到两个非常不满意的解决方案来正确在线构建 API 文档：

恢复到 conda 方法来安装完整的依赖项。这是一个巨大的矫枉过正，因为构建文档只需要我包中的文档字符串，而不是那些 C/Fortran 扩展。
或者，更改我包的setup.py ，这样我就可以在没有--no-deps选项的情况下安装它。这对我的包裹本身不利。

所以我仍在寻找更好的解决方案。任何建议，将不胜感激！

额外的信息

以下是在我的笔记本电脑上构建正确文档的完整步骤：

conda create -n doc python=3.6
conda activate doc
conda install -c conda-forge pandoc
pip install numpydoc ipython nbsphinx sphinx_rtd_theme
pip install --no-deps xesmf
git clone https://github.com/JiaweiZhuang/xesmf
cd xesmf/doc
make html

正确的 API 页面如下所示：
Screen Shot 2019-03-20 at 3 23 15 PM

Support

资料来源

JiaweiZhuang

👍3

最有用的评论

@stsewd感谢您的建议！我调整了setup.py以便：

on_rtd = os.environ.get('READTHEDOCS') == 'True'
if on_rtd:
    INSTALL_REQUIRES = []
else:
    INSTALL_REQUIRES = ['esmpy', 'xarray', 'numpy', 'scipy']

（https://github.com/JiaweiZhuang/xESMF/commit/5ce3364bfbd3081aad848c5cf4ac54a287ca236e）

感觉有点hacky，但确实解决了问题。再次感谢。

JiaweiZhuang 于 2019-03-21

👍3 ❤2

所有3条评论

我认为我们不会为 pip 添加更多选项，抱歉。我想到的一种解决方案是使用READTHEDOCS变量https://docs.readthedocs.io/en/stable/faq.html#how -do-i-change-behavior-for-阅读 setup.py 文件中的文档。

stsewd 于 2019-03-20

如果您需要一些依赖项，您可以仅为您的文档创建一个自定义需求文件。