autodoc-skip-member support

[barry-gallagher]

I just started trying to get class docs today and liked how the automodapi was formatting them with one class per file and not having to hand enter all the names. I had trouble getting autosummary to do this by myself. The only issue I had was the :skip: was limiting and I wanted to use a regular expression to exclude some things. I dug around and found the generate_automodsumm_docs() in automodsumm.py doesn't have the skip_member support like generate_autosummary_content in generate.py from autosummary. I added/modified the code below to get it to almost work right for me.

It doesn't create the event quite right, but a little hacking on my conf.py gets around it for now. Hopefully you can add this support at some point in the future.

Thanks for the nice docs!

            def skip_member(obj, name, objtype) -> bool:
                try:
                    return app.emit_firstresult('autodoc-skip-member', objtype, name, obj, False, {})
                except Exception as exc:
                    print('autosummary: failed to determine %r to be documented. the following exception was raised:\n%s',
                                   name, exc, type='autosummary')
                    return False

            def get_members_mod(obj, typ, include_public=[]):
                """
                typ = None -> all
                """
                items = []
                for name in dir(obj):
                    try:
                        documenter = get_documenter(app, safe_getattr(obj, name), obj)
                    except AttributeError:
                        continue
                    skipped = skip_member(type(safe_getattr(obj, name)), name, obj)
                    if skipped is True:
                        continue
                    if typ is None or documenter.objtype == typ:
                        items.append(name)
                public = [x for x in items
                          if x in include_public or not x.startswith('_')]
                return public, items

            def get_members_class(obj, typ, include_public=[],
                                  include_base=False):
                """
                typ = None -> all
                include_base -> include attrs that are from a base class
                """
                items = []

                # using dir gets all of the attributes, including the elements
                # from the base class, otherwise use __slots__ or __dict__
                if include_base:
                    names = dir(obj)
                else:
                    # Classes deriving from an ABC using the `abc` module will
                    # have an empty `__slots__` attribute in Python 3, unless
                    # other slots were declared along the inheritance chain. If
                    # the ABC-derived class has empty slots, we'll use the
                    # class `__dict__` instead.
                    declares_slots = (
                        hasattr(obj, '__slots__') and
                        not (type(obj) is abc.ABCMeta and
                             len(obj.__slots__) == 0)
                    )

                    if declares_slots:
                        names = tuple(getattr(obj, '__slots__'))
                    else:
                        names = getattr(obj, '__dict__').keys()

                for name in names:
                    try:
                        documenter = get_documenter(app, safe_getattr(obj, name), obj)
                    except AttributeError:
                        continue
                    skipped = skip_member(type(safe_getattr(obj, name)), name, obj.__class__)
                    if skipped is True:
                        continue
                    if typ is None or documenter.objtype == typ:
                        items.append(name)
                    elif typ == 'attribute' and documenter.objtype == 'property':
                        # In Sphinx 2.0 and above, properties have a separate
                        # objtype, but we treat them the same here.
                        items.append(name)
                public = [x for x in items
                          if x in include_public or not x.startswith('_')]
                return public, items