CODEWITHSUNDEEP
pythonpython-sphinxtoctree
paugier
paugier

Reputation: 1878

autosummary with toctree also lists imported members

I use Sphinx and autosummary to produce the documentation of a Python software. It works well but the produced .rst files also list the imported functions and classes, which is not the behaviour I would like.

For example a package "packageex" with the docstring:

"""
Package Example (:mod:`packageex`)
==================================

.. currentmodule:: packageex
.. autosummary::
   :toctree:

   module0
   module1
"""

would produce a file packageex.module0.rst with

Module0 (:mod:`packageex.module0`)
=================================

.. currentmodule:: packageex.module0

.. rubric:: Functions

.. autosummary::

   f0
   f1
   f2_imported
   f3_imported

.. rubric:: Classes

.. autosummary::

   Class0
   ClassImported

Is there a way to list only the functions and classes defined in the module (and not those imported)?

In the doc of autodoc (http://sphinx-doc.org/latest/ext/autodoc.html), there is "In an automodule directive with the members option set, only module members whose __module__ attribute is equal to the module name as given to automodule will be documented. This is to prevent documentation of imported classes or functions. Set the imported-members option if you want to prevent this behaviour and document all available members. Note that attributes from imported modules will not be documented, because attribute documentation is discovered by parsing the source file of the current module." Is it possible to get the same behaviour with autosummary?

Upvotes: 4

Views: 3106

Answers (1)

paugier
paugier

Reputation: 1878

As mentioned by mzjn, it seems to be a known strange behaviour of the extension autosummary. In order to get the wanted behaviour (i.e. to prevent the listing of imported objects), I have just modified the function get_members (l. 166 of sphinx.ext.autosummary.generate) like so:

def get_members(obj, typ, include_public=[], imported=False):
    items = []
    for name in dir(obj):
        try:
            obj_name = safe_getattr(obj, name)
            documenter = get_documenter(obj_name, obj)
        except AttributeError:
            continue
        if documenter.objtype == typ:
            try:
                cond = (
                    imported or 
                    obj_name.__module__ == obj.__name__
                    )
            except AttributeError:
                cond = True
            if cond:
                items.append(name)
    public = [x for x in items
              if x in include_public or not x.startswith('_')]
    return public, items

Upvotes: 5

Related Questions