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

Question

Question

Is there a way to generate sphinx documentation of a child class without installing the library containing its parent class on GitLab CI (or any comparable CI tool)?

Edit : I have 7 such classes and ca. 10 member functions per class on average to be documented. Thus, an automated solution is strongly preferred, as it cost too much time to hard-code the docstrings into the .rst files.

If the problem cannot be solved by changing Sphinx settings alone, then I will only accept an answer that provides clear instructions to get the desired documentation generated and published.

Context

Specifically, I made a child class of tensorflow.keras.callbacks.Callback and want to show its docstring on the documentation page. By default, Sphinx has to import everything generate documentation. But it doesn't seem right to install tensorflow (and tens of other libraries that sums up to several GBs) on the CI image just for this. I just want my docstring to be shown and I don't care about their parent classes. This is the reason why I turned on autodoc_mock_imports in conf.py (the Sphinx configuration file). The docs were build without error, but the documentation of that child class was missing.

In the MWE below, the customized class is keras_callback.py . The sphinx directives is contained in keras_callback.rst as follows.

.. automodule:: keras_callback

    :members:
    :inherited-members:

Minimum Working Example

There is an MWE and Sphinx-generated docs on my GitLab repo to reproduce the problem.

Desired documentation of the child class looks like this.

At the minimum, the documentation of my custom function should be shown. Member functions from the parent class can be turned off.

Answer 1

In addition to the "auto" directives (such as automodule and autoclass ) that extract documentation from Python code, Sphinx also provides "non-auto" directives ( module , class etc.) where all the documentation goes into.rst files.

My suggestion is to replace .. automodule:: keras_callback with the following:

.. 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

I finally found a simple workaround: Build locally and then overwrite the CI-built page using the locally built page. If the desired page need not rebuild frequently, then this solution may save considerable time hard-coding the members.

Steps

1. Build locally without autodoc_mock_imports in conf.py .

2. Copy the correct webpage ( keras_callback.html ) to _static folder.

3. Re-enable autodoc_mock_imports .

4. Add a cp command to overwrite the CI-built page in .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

5. Commit, push and check the webpage. Worked for this particular MWE (not shown in the repo).

The drawback is of course that the maintainer has to rebuild that page manually whenever it is updated. But this should suffice for many small independent projects because docs-publishing usually happens only at the very end stage of development.