Skip to content

__init__ docstrings and class parameter definitions do not show up in read-the-docs API pages

__init__ methods are not rendered in the read-the-docs API pages. For example, the documentation for Schedule looks like

image

This is problematic since we tend to put all parameter definitions inside the __init__ method:

image

and this information is now hidden on read-the-docs.

Possible fixes:

  • instruct sphinx and/or auto-api to include __init__ methods in the docs
  • move all parameter-definitions used to instantiate a class to the top-level docstring.

The 2nd fix is a bit more work as this will have to be done for every class definition in the code base (we have about 300 class definitions). However, I think this greatly improves readability. I looked at a few other software packages and they use the same standard. See pandas' DataFrame definition for example:

image