astropy / astropy/sphinx-automodapi

autodoc-skip-member support

Open
#94 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
67
Forks
48
Avg merge
11h 52m
Merged PRs (30d)
1

Description

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
```

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in automodsumm.py at generate_automodsumm_docs() and compare its member discovery with generate.py's generate_autosummary_content(), especially the autodoc-skip-member event handling described in the issue. Use the supplied get_members_mod() and get_members_class() examples as reference; done means regex-based autodoc-skip-member exclusions work for generated automodsumm documentation without a conf.py workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.