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 构建的页面。如果所需的页面不需要频繁重建，那么此解决方案可以节省大量对成员进行硬编码的时间。脚步本地构建，无需 autodoc_mock_importsin conf.py.将正确的网页 ( keras_callback.html) 复制到_static文件夹。重新启用autodoc_mock_imports.添加一个cp命令来覆盖 CI 构建的页面.gitlab-ci.ymlimage: 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提交、推送并检查网页。为这个特定的 MWE 工作（未在存储库中显示）。当然，缺点是维护者必须在更新页面时手动重建该页面。但这对于许多小型独立项目来说应该足够了，因为文档发布通常只发生在开发的最后阶段。