Omit (or format) the value of a variable when documenting with Sphinx

Question

I'm currently documenting a whole module with autodoc. However, I define several variables on the module level that contain long lists or dicts. They are included in the documentation together with the values, and the values are unformatted, so it looks like a 10-lines mess. What I want is for the docstring of those variables to be included, but for the values to be omitted or at least nicely formatted.

I've tried to exclude the variable from automodule directive and add it like that:

.. automodule:: foo.bar
   :members:
   :exclude-members: longstuff

   .. py:data:: longstuff

This resulted in that only the variable name was included, whereas both the docstring and the value of longstuff were not present in the documentation.

How can I keep the docstring and get rid of the value (or have it nicely formatted) at the same time?

Answer 1

There is no simple configuration setting for omitting values of module level variables in the output. But you can do it by modifying the DataDocumenter.add_directive_header() method in autodoc.py. The crucial line in that method is

self.add_line(u'   :annotation: = ' + objrepr, '<autodoc>')

where objrepr is the value.

The following monkey patch added to conf.py works for me:

from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter

def add_directive_header(self, sig):
    ModuleLevelDocumenter.add_directive_header(self, sig)
    # Rest of original method ignored

DataDocumenter.add_directive_header = add_directive_header