Search code examples
python-sphinxprivate-members

Selectively including private member functions in sphinx documentation

I want to autogenerate documentation for a python project. I managed to get a barebones pipeline working with sphinx, but the output currently includes literally everything and I want to be more selective about what is and is not documented in terms of class members and methods.

In particular, I would like to document "private" member functions for some classes (the base classes, so that people subclassing them have access to the full description of the functions they need to override), but not all. The internet pointed me to the :private-members:, but its use results in an error and no documentation being generated. I managed to get it working by setting the default behavior in conf.py:

extensions = ['sphinx.ext.autodoc']

autodoc_default_options = {
    "members": True,
    "undoc-members": False,
    "private-members": True}

but this applies universally and I do not want private members documented for all classes. How can I achieve this?

EDIT for clarity.

If I remove the autodoc_default_options definition in conf.py, I can get it to compile with index.rst like so:

.. automodule:: app.utils.MetaReader
    :private-members:
.. automodule:: app.utils.MetaWriter
    :private-members:
.. automodule:: app.utils.MetaFilter
    :private-members:
.. automodule:: app.utils.MetaEventFinder
    :private-members:
.. automodule:: app.plugins.filters.BesselFilter
    :members:   
.. automodule:: app.plugins.datareaders.ChimeraReader20240101
    :members:   
.. automodule:: app.plugins.datareaders.ChimeraReader20240501
    :members:   
.. automodule:: app.plugins.datawriters.Pod5Writer
    :members:   
.. automodule:: app.plugins.eventfinders.ClassicBlockageFinder
    :members:   
.. automodule:: app.models.main_model
    :private-members:   
.. automodule:: app.models.reader
    :private-members:   
.. automodule:: app.controllers.file_load_controller
    :private-members:   
.. automodule:: app.controllers.main_controller
    :private-members:   
.. automodule:: app.views.file_load_view
    :private-members:   
.. automodule:: app.views.main_view
    :private-members:   
.. automodule:: app.views.raw_data_view
    :private-members:

However, as far as I can tell, modules with :private-members: indicated give the same output as those with just :members: - and in both cases, private member functions are not part of the generated docs.

If I add BOTH :private-members: and :members:, I get the following error:

reading sources... [100%] index
WARNING: missing attribute mentioned in :members: option: module app.utils.MetaReader, attribute :members:

(+ the same error for all other modules with both)

Solution

  • By looking at the names of the things you want to autodoc, I reckon you are trying to automodule a Class, isntead of autoclass a Class.