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

编程问答 2022-08-13

问题描述

问题

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

编辑：我有7个此类，大约每个类平均要记录10个成员函数。因此，强烈建议使用自动化解决方案，因为将文档字符串硬编码到.rst文件中会花费太多时间。

如果仅通过更改Sphinx设置不能解决问题，那么我将只接受提供明确说明的答案，以获取所需的文档并发布。

上下文

具体来说，我做了tensorflow.keras.callbacks.Callback的子班 并希望在文档页面上显示其文档字符串。 默认情况下，Sphinx必须导入一切生成文档。但 安装tensorflow和其他数十个库似乎不正确 为此，在CI映像上总计为几个GB）。我只想要我的文档字符串 被展示出来，我不在乎他们的父母班。这就是原因 为什么我在autodoc_mock_imports中打开conf.py（狮身人面像 配置文件）。该文档的构建没有错误，但是文档 那个孩子班级的人缺了。

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

.. automodule:: keras_callback

    :members:
    :inherited-members:

最小工作示例

有一个MWE 和Sphinx-generated docs到我的GitLab存储库中以重现该问题。

所需的子类文档如下所示。

enter image description here

至少应显示我的自定义函数的文档。可以关闭父类中的成员函数。

解决方法

除了从Python代码中提取文档的"auto" directives（例如automodule和autoclass）之外，Sphinx还提供了"non-auto" directives（module，{ {1}}等），所有文档都放在.rst文件中。

我的建议是将class替换为以下内容：

.. automodule:: keras_callback
,

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

步骤

  1. 在autodoc_mock_imports中没有 conf.py在本地构建。

  2. 将正确的网页（keras_callback.html）复制到_static文件夹中。

  3. 重新启用autodoc_mock_imports。

  4. 添加cp命令以覆盖.gitlab-ci.yml中的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
  1. 提交，推送并检查网页。为此特定工作 MWE（在存储库中未显示）。

缺点当然是维护者必须重建该页面 每次更新时手动进行。但这足以满足许多小 独立项目，因为文档发布通常仅在 发展的最后阶段。

autodocgitlab-cipythonpython-sphinx