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

Question

题

有没有一种方法可以生成子 class 的 sphinx 文档，而无需在 GitLab CI（或任何类似的 CI 工具）上安装包含其父 class 的库？

编辑：我有 7 个这样的类和 ca。 平均每个 class 有 10 个成员函数被记录。 因此，强烈推荐使用自动化解决方案，因为将文档字符串硬编码到.rst文件中会花费太多时间。

如果仅通过更改 Sphinx 设置无法解决问题，那么我将只接受提供明确说明以生成和发布所需文档的答案。

语境

具体来说，我做了一个孩子 class of tensorflow.keras.callbacks.Callback并想在文档页面上显示它的文档字符串。 默认情况下，Sphinx 必须导入所有生成文档。 但是仅仅为了这个就在 CI 镜像上安装tensorflow （以及其他数十个库，总计达数 GB）似乎并不合适。 我只想显示我的文档字符串，我不关心它们的父类。 这就是为什么我在conf.py （Sphinx 配置文件）中打开autodoc_mock_imports的原因。 文档构建时没有错误，但缺少该子项 class 的文档。

在下面的 MWE 中，自定义的 class 是keras_callback.py 。 sphinx 指令包含在keras_callback.rst中，如下所示。

.. automodule:: keras_callback

    :members:
    :inherited-members:

最小工作示例

我的 GitLab 存储库中有一个MWE和Sphinx 生成的文档来重现该问题。

孩子 class 的所需文档如下所示。

至少，应该显示我的自定义 function 的文档。 来自父级class的成员函数可以关闭。

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. 在conf.py中不autodoc_mock_imports在本地构建。

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

3. 重新启用autodoc_mock_imports 。

4. 在.gitlab-ci.yml中添加cp命令覆盖 CI 构建的页面

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

5. 提交，推送并检查网页。 为这个特定的 MWE 工作（未在 repo 中显示）。

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