Search code examples
python-sphinx

sphinx-autodoc ignores default settings in conf.py

We have a Python project and do this to generate documents:

sphinx-apidoc --module-first -f -o source/ ../src

make html

In recent sphinx (6.1.3), we notice a problem. One of the classes has a class variable that is a Pandas dataframe. The thing is read from a CSV file before the init function and the Sphinx html output has the whole table included in the documentation. I believe this happens because the table is an undocumented member and Sphinx is doing what it thinks is correct. I have tried many fixes, blundering about in the dark.

The defaults for sphinx-autodoc create rst files like this:

.. automodule:: my.app
   :members:
   :undoc-members:
   :show-inheritance:

If I hand edit the rst file, I can stop the bad result from happening. I thought that "no-undoc-members would solve problem, but it does not. However, adding the exclude param really works.

.. automodule:: my.app
   :members:
   :no-undoc-members:
   :show-inheritance:
   :exclude-members: form, form_long

The problem with that "fix" is that autodoc has to update the rst files every time, it erases that hand edited rst.

I have tried these approaches to change autodoc behavior.

  1. Add docstrings for the class variable in the Python source. If I specify the docstring, then Sphinx won't print the whole Pandas table will it? It is supposed to work if I specify before a member variable like #: blah or after with """ blah """. Did not help.

  2. In source/conf.py add this:

autodoc_default_options = {
    'undoc-members': False,
    'exclude-members': 'form'
}

However, after adding that to conf.py, it seems like sphinx-autodoc does not pay attention. It uses same old rst file defaults. Another problem is that, even if it were used, it seems to not allow me to write more than one member in exclude-members. I mean, I don't know correct format and everything I've tried causes an error in make html

Thanks in advance if you help me see what I'm doing incorrectly.

Solution

  • As @mzjn explained, sphinx-apidoc DOES NOT read the conf.py file. I did not find a dependable way to change default content of the RST files created by sphinx-apidoc.

    Here is how we deal with the specific problem that undocumented class objects are printed out into the documentation. This does not change the rst files themselves, it changes the conversion into HTML. The make process does read conf.py and we can insert code in there to block the insertion of tables for these objects.

    def skip_member(app, what, name, obj, skip, options):
    if name in ['map', 'map_long', 'vm_map']:
        return True
    else:
        return None

def setup(app):
    app.connect('autodoc-skip-member', skip_member)

    This example prevents the documentation for 3 particular variables, but you can put a class name if you want to block all variables from a class.

    I do not know why inserting docstrings for those previously undocumented strings has no effect. Also don't understand what autodoc_default_options in the conf.py is supposed to do, if anything. Instructions here just don't make sense to me https://smobsc.readthedocs.io/en/stable/usage/extensions/autodoc.html

    autodoc