Python-sphinx：child class 的文档在启用 "autodoc_mock_imports" 时不会显示
Python-sphinx: documentation of a child class won't show when "autodoc_mock_imports" is enabled
问题
有没有办法生成 child class 的 sphinx 文档而不用
在 GitLab CI 上安装包含其 parent class 的库
（或任何类似的 CI 工具）？
编辑：我有 7 个这样的 classes 和 ca。平均每个 class 有 10 个成员函数需要记录。因此，强烈推荐使用自动化解决方案，因为将 hard-code 文档字符串放入 .rst 文件会花费太多时间。
如果仅通过更改 Sphinx 设置无法解决问题，那么我将只接受提供明确说明以生成和发布所需文档的答案。
上下文
具体来说，我制作了 child class of tensorflow.keras.callbacks.Callback
并希望在文档页面上显示其文档字符串。
默认情况下，Sphinx 必须导入所有生成文档。但
安装 tensorflow （以及其他数十个库）似乎不正确
CI 图像上总计达数 GB）仅此而已。我只想要我的文档字符串
显示出来，我不关心他们的 parent classes。这就是原因
为什么我在 conf.py 中打开 autodoc_mock_imports（Sphinx
配置文件）。文档构建没有错误，但是文档
其中 child class 丢失了。
在下面的MWE中，自定义的class是keras_callback.py。 sphinx 指令包含在 keras_callback.rst 中，如下所示。
.. automodule:: keras_callback
:members:
:inherited-members:
最小工作示例
有一个MWE
和 Sphinx-generated docs 在我的 GitLab 存储库上重现该问题。
child class 的所需文档如下所示。
至少应该显示我的自定义函数的文档。来自parentclass的成员函数可以关闭。
除了 "auto" directives (such as automodule and autoclass) that extract documentation from Python code, Sphinx also provides "non-auto" directives（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
我终于找到了一个简单的解决方法：在本地构建然后覆盖 CI-built
页面使用本地构建的页面。如果所需的页面不需要经常重建，那么此解决方案可能会节省相当多的时间 hard-coding 成员。
步骤
本地构建 没有 autodoc_mock_imports in conf.py.
将正确的网页 (keras_callback.html) 复制到 _static 文件夹。
Re-enable autodoc_mock_imports.
添加cp命令覆盖.gitlab-ci.yml
中的CI-built页面
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
- 网页提交、推送、检查。为这个特别工作
MWE（未在回购中显示）。
缺点当然是维护者必须重建那个页面
每当它更新时手动。但这应该足以满足许多小型
独立项目，因为 docs-publishing 通常只发生在
发展的最后阶段。
问题
有没有办法生成 child class 的 sphinx 文档而不用 在 GitLab CI 上安装包含其 parent class 的库 （或任何类似的 CI 工具）？
编辑：我有 7 个这样的 classes 和 ca。平均每个 class 有 10 个成员函数需要记录。因此，强烈推荐使用自动化解决方案，因为将 hard-code 文档字符串放入 .rst 文件会花费太多时间。
如果仅通过更改 Sphinx 设置无法解决问题，那么我将只接受提供明确说明以生成和发布所需文档的答案。
上下文
具体来说，我制作了 child class of tensorflow.keras.callbacks.Callback
并希望在文档页面上显示其文档字符串。
默认情况下，Sphinx 必须导入所有生成文档。但
安装 tensorflow （以及其他数十个库）似乎不正确
CI 图像上总计达数 GB）仅此而已。我只想要我的文档字符串
显示出来，我不关心他们的 parent classes。这就是原因
为什么我在 conf.py 中打开 autodoc_mock_imports（Sphinx
配置文件）。文档构建没有错误，但是文档
其中 child class 丢失了。
在下面的MWE中，自定义的class是keras_callback.py。 sphinx 指令包含在 keras_callback.rst 中，如下所示。
.. automodule:: keras_callback
:members:
:inherited-members:
最小工作示例
有一个MWE 和 Sphinx-generated docs 在我的 GitLab 存储库上重现该问题。
child class 的所需文档如下所示。
至少应该显示我的自定义函数的文档。来自parentclass的成员函数可以关闭。
除了 "auto" directives (such as automodule and autoclass) that extract documentation from Python code, Sphinx also provides "non-auto" directives（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
我终于找到了一个简单的解决方法：在本地构建然后覆盖 CI-built 页面使用本地构建的页面。如果所需的页面不需要经常重建，那么此解决方案可能会节省相当多的时间 hard-coding 成员。
步骤
本地构建 没有
autodoc_mock_importsinconf.py.将正确的网页 (
keras_callback.html) 复制到_static文件夹。Re-enable
autodoc_mock_imports.添加
中的CI-built页面cp命令覆盖.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
- 网页提交、推送、检查。为这个特别工作 MWE（未在回购中显示）。
缺点当然是维护者必须重建那个页面 每当它更新时手动。但这应该足以满足许多小型 独立项目，因为 docs-publishing 通常只发生在 发展的最后阶段。