Python: Sphinx namedtuple documentation

Question

I'm trying to document namedtuple. When I build the docs I get a warning WARNING: duplicate object description and same empty functions after documented ones. For example:

How to delete those aliases? I've already tried this solution , writing few functions to conf.py to create empty properties.

Also, I think it worth to mention that after building I get a note to use :noindex: but I don't understand where should I use it? In my docstring, rst file or somewhere else?

Code example:

File = namedtuple("File", ["path", "size", "extension",
                           "adate", "mdate", "links",
                           "user_owner", "group_owner",
                           "inode", "device", "permissions",
                           "depth"])
"""File attributes.

.. py:attribute:: path

    **-** path to the found file

     .. note::
        depending on command-line arguments can be absolute or relative
...

Answer 1

I ran into the same problem documenting namedtuples. Here is my solution.

Do not use the :members: option in your autodoc directives.

Example.rst file:

.. documentation for module with namedtuple

Module with namedtuple
======================

.. automodule:: packagename.modulename

.. autoclass:: packagename.modulename.namedtuplename

Also, to get Sphinx to pick up my namedtuple docstring I had to use its __doc__ attribute. So using your example:

File = namedtuple("File", ["path", ..., "depth"])
File.__doc__ = """File attributes.

.. :attribute:: path
...
"""

Explanation

• the automodule:: directive picks up the module's docstring
• the autoclass:: directive picks up the namedtuple's docstring.

The preferred (and usual) approach with autodoc is to use the :members: option and recursively document everything in the module. But when the module contains a namedtuple, using the :members: option (with either directive) generates aliases in the documentation.

With automodule:: , the :members: option causes Sphinx to recursively document the members: first the members of the module (the namedtuple's class), then the members of the members (the attributes of that class). This picks up duplicate attributes for the class created by the namedtuple, resulting in the alias problem.

With autoclass: , the :members: option again picks up duplicate class attributes, resulting in the alias problem.

Because _fields

The underlying mechanism for the duplicates is that the class attributes documented in the docstring are already documented as the namedtuple's field names ( see the docs ). This behavior is built in to namedtuples; I'm not sure how to override it.

To see this underlying mechanism, open a REPL and list the _fields of your namedtuple:

>>> File._fields

To see where the duplicate documentation problem is causing the alias messages, get help on the namedtuple:

>>> help(File)

If you keep scrolling through the documentation, you should eventually see something like this:

 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  adate
 |      Alias for field number 3
 |
 |  depth
 |      Alias for field number 11

Note

It is also important that the namedtuple uses the same name as its type, just as you did:

File = namedtuple("File", ["path", ..., "depth"])

This is convention anyway, but since it is not required it is worth noting that using different names will cause the alias problem for the class instead of the class attributes.

Answer 2

sphinx-toolbox provides a solution to this, for more info, see here .

To use it, you will need to install sphinx-toolbox , for pip user:

pip install sphinx-toolbox

Then insert the extension to conf.py .

extensions = [
    ...
    'sphinx_toolbox.more_autodoc.autonamedtuple',
    ]

and no more configurations:)

Answer 3

I ran into a, I think, much better solution than the accepted answer, just wanted to share it:

Just write this in your conf.py:

# -- Post process ------------------------------------------------------------
import collections
def remove_namedtuple_attrib_docstring(app, what, name, obj, skip, options):
    if type(obj) is collections._tuplegetter:
        return True
    return skip


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

This remove all parameters auto documented with this "Alias for field.." from all NamedTuple classes.

explanation

This uses the autodoc event autodoc-skip-member which triggers an handler each time it comes accross any type of member

• app.connect('autodoc-skip-member', remove_namedtuple_attrib_docstring) attaches the handler remove_namedtuple_attrib_docstring to the event
• The handler returns true if the member is a tuplegetter and return the default skipping values otherwise