2

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.

enter image description here

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

Bill Huang
  • 4,491
  • 2
  • 13
  • 31
  • An option might be to forgo autodoc for this class and instead write the documentation using the `py:class` and `py:method` directives. https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html?highlight=domain#directive-py-class – mzjn Aug 30 '20 at 08:32
  • OK, I've read that page, but it lacks the context explaining why use it, where to begin with, what to do, and what result should I expect. May you please provide some hints? – Bill Huang Aug 31 '20 at 05:24

2 Answers2

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
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • Thanks for your clear explanation. I have 7 such child classes and ca. 10 member functions per class on average. Do I really have to hard-code all of these manually in such a laborious way? I would be very shocked if this is the case. BTW, I will accept this answer if no easier option appears after one week. – Bill Huang Aug 31 '20 at 14:25
0

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

Bill Huang
  • 4,491
  • 2
  • 13
  • 31