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.
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:
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.
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
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.
Build locally without autodoc_mock_imports
in conf.py
.
Copy the correct webpage ( keras_callback.html
) to _static
folder.
Re-enable autodoc_mock_imports
.
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
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.
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.