Python-sphinx：启用“autodoc_mock_imports”时不会显示子类的文档

Question

问题有没有一种方法可以生成子类的 sphinx 文档，而无需在 GitLab CI（或任何类似的 CI 工具）上安装包含其父类的库？编辑：我有 7 个这样的课程，大约有 7 个。平均每个类有 10 个成员函数需要记录。因此，强烈推荐自动化解决方案，因为将文档字符串硬编码到文件中会花费太多时间.rst。如果仅通过更改 Sphinx 设置无法解决问题，那么我只会接受提供明确说明以生成和发布所需文档的答案。语境具体来说，我创建了一个子类tensorflow.keras.callbacks.Callback ，并希望在文档页面上显示其文档字符串。默认情况下，Sphinx 必须导入生成文档的所有内容。tensorflow但仅仅为此在 CI 映像上安装（以及数十个其他库，总计达数 GB）似乎并不正确。我只想显示我的文档字符串，我不关心他们的父类。autodoc_mock_imports这就是我在conf.py（Sphinx配置文件）中开启的原因。文档的构建没有错误，但缺少该子类的文档。在下面的MWE中，定制的类是keras_callback.py. sphinx 指令包含keras_callback.rst如下。.. automodule:: keras_callback     :members:         :inherited-members:最小工作示例我的 GitLab 存储库上有MWE 和Sphinx 生成的文档来重现该问题。子类所需的文档如下所示。至少，应该显示我的自定义函数的文档。可以关闭父类的成员函数。

Answer 1

除了从 Python 代码中提取文档的“自动”指令（例如automodule和autoclass）之外，Sphinx 还提供“非自动”指令（module等class），其中所有文档都放入 .rst 文件中。

我的建议是替换.. automodule:: keras_callback为以下内容：

.. class:: keras_callback.MyKerasCallback
 
   An inherited Keras ``Callback`` class.
 
   .. method:: __init__(dic=None) 
      Constructor
 
   .. method:: on_epoch_begin(epoch, logs=None)           
      Inherited method
 
   .. method:: custom_method
 
      Custom method

.. autofunction:: keras_callback.util_func

Answer 2

我终于找到了一个简单的解决方法：本地构建，然后使用本地构建的页面覆盖 CI 构建的页面。如果所需的页面不需要频繁重建，那么此解决方案可以节省大量对成员进行硬编码的时间。

脚步

1. 本地构建，无需 autodoc_mock_importsin conf.py.

2. 将正确的网页 ( keras_callback.html) 复制到_static文件夹。

3. 重新启用autodoc_mock_imports.

4. 添加一个cp命令来覆盖 CI 构建的页面.gitlab-ci.yml

image: python:3.7-alpine

pages:
script:
- pip install sphinx sphinx-rtd-theme recommonmark
- sphinx-build -d _build/doctrees . _build/html
- mv _build/html public
- cp _static/keras_callback.html public
artifacts:
    paths:
    - public
    only:
    - master

1. 提交、推送并检查网页。为这个特定的 MWE 工作（未在存储库中显示）。

当然，缺点是维护者必须在更新页面时手动重建该页面。但这对于许多小型独立项目来说应该足够了，因为文档发布通常只发生在开发的最后阶段。