sphinx-autodoc ignores default settings in conf.py

Question

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.

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

When you say sphinx-autodoc, I presume that you mean sphinx-apidoc. That tool does not use any settings in conf.py. See https://stackoverflow.com/a/36431748/407651 — mzjn, Mar 30 '23 at 06:35
Regarding "it erases that hand edited rst": it is not mandatory to run sphinx-apidoc over and over again. An option is to save the hand edited RST files. See https://stackoverflow.com/a/28481785/407651 — mzjn, Mar 30 '23 at 06:57
That link explains much more clearly than sphinx docs. We found a solution by adding a setup function in conf.py. I will come back and give example. — pauljohn32, Apr 01 '23 at 01:34

score 1 · Accepted Answer · answered Apr 05 '23 at 15:37

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

A few notes, what `autodoc_default_options` does is choosing the options under each autodoc directive (e.g. `autoclass`) **when you omit them**. So if you never want undocumented members put `:no-undoc-members:` in the `conf.py` and that will save you writing that option under every directive in the `rst` files (it will make them more concise)... For up-to-date `autodoc` documentation see the [official docs](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). I generally only use sphinx-apidoc once at the beginning of a project, afterwards I keep the structure by hand. — bad_coder, Apr 05 '23 at 15:55

sphinx-autodoc ignores default settings in conf.py

1 Answers1