33

I want to use sphinx's autodoc-skip-member event to select a portion of the members on a certain python class for documentation.

But it isn't clear from the sphinx docs, and I can't find any examples that illustrate: where do I put the code to connect this? I see Sphinx.connect and I suspect it goes in my conf.py, but when I try variations on this code in conf.py I can't find the app object that I should connect():

def maybe_skip_member(app, what, name, obj, skip,
                                  options):
    print app, what, name, obj, skip, options
    return False

# This is not even close to correct:
#from sphinx.application import Sphinx
#Sphinx().connect('autodoc-skip-member', maybe_skip_member)

A pointer to a simple example would be ideal.

3 Answers 3

46

Aha, last ditch effort on a little googling turned up this example, scroll down to the bottom. Apparently a setup() function in conf.py will get called with the app. I was able to define the following at the bottom of my conf.py:

def maybe_skip_member(app, what, name, obj, skip, options):
    print app, what, name, obj, skip, options
    return True

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

Which is obviously useless (it skips everything), but that's the minimal example I was looking for and couldn't find...

16

This answer expands upon the answer by bstpierre. It implements autodoc-skip-member. Below is the relevant portion from my conf.py:

autodoc_default_flags = ['members', 'private-members', 'special-members',
                         #'undoc-members',
                         'show-inheritance']

def autodoc_skip_member(app, what, name, obj, skip, options):
    # Ref: https://stackoverflow.com/a/21449475/
    exclusions = ('__weakref__',  # special-members
                  '__doc__', '__module__', '__dict__',  # undoc-members
                  )
    exclude = name in exclusions
    # return True if (skip or exclude) else None  # Can interfere with subsequent skip functions.
    return True if exclude else None
 
def setup(app):
    app.connect('autodoc-skip-member', autodoc_skip_member)
1
  • For me, this has no effect, all the new rst files are created by sphinx-autodoc as they were before. Is this approach supposed to work now?
    – pauljohn32
    Mar 29, 2023 at 14:57
4

If anyone comes searching for same question but for AutoAPI instead of autodoc, the below snippet successfully excludes all attributes and methods from the AutoAPI generated documentation that begin with _; this isn't a great idea in practice but I wanted to start with something drastic for ease of detection.

def autoapi_skip_member(app, what, name, obj, skip, options):
    """Exclude all private attributes, methods, and dunder methods from Sphinx."""
    import re
    exclude = re.findall('\._.*', str(obj))
    return skip or exclude


def setup(app):
    """Add autoapi-skip-member."""
    app.connect('autoapi-skip-member', autoapi_skip_member)

One quirk/oddity to call out is that that the same functions applied to name instead of str(obj) in the autoapi_skip_member function doesn't seem to work, which I was (apparently) mistakenly under the impression were the same thing ('fully qualified name of the object' per the AutoAPI docs).

This includes when throwing in something like the below to detect methods that start with _:

or (hasattr(obj, '__name__') and str(obj.__name__).startswith('_'))
1

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.