astropy / astropy/sphinx-automodapi

Add option to exclude imported members

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

Description

First of all, thanks for this great extension! I've found it very useful, except for one detail:

When using either the `automodapi` or `automodsumm` directives, all imported members of a module are included, and there does not appear to be a way to change this behavior. The behavior I would like is to only include local members and exclude imported members.

There is [one StackOverflow question](https://stackoverflow.com/questions/47344477/how-to-exclude-imports-from-automodapi-output) on this issue with a response that suggests modifying `__all__`, which is a sub-optimal solution. The `:skip:` option could be used, but is sub-optimal for the same reason, that is, it requires a hardcoded list of members.

Conveniently, it appears that `utils.find_mod_objs()` already has a `onlylocals` argument which will, as expected, return only local members and exclude imported members. If this call within `Automodsumm.run()`: https://github.com/astropy/sphinx-automodapi/blob/master/sphinx_automodapi/automodsumm.py#L135
is replaced with `localnames, fqns, objs = find_mod_objs(modname, onlylocals=True)`, this produces the desired output.

What I am currently doing is monkey-patching this out in `conf.py`:
```python
def patch_automodapi(app):
"""Monkey-patch the automodapi extension to exclude imported members """
from sphinx_automodapi import automodsumm
from sphinx_automodapi.utils import find_mod_objs

def find_local_mod_objs(*args, **kwargs):
kwargs['onlylocals'] = True
return find_mod_objs(*args, **kwargs)

automodsumm.find_mod_objs = find_local_mod_objs

def setup(app):
app.connect("builder-inited", patch_automodapi)
```

Instead of monkey-patching, it would be great if this could be exposed as one or more options in automodapi. Autosummary has a related setting called `autosummary_imported_members`, so I would suggest doing one or more of the following:

1. Respect the `autosummary_imported_members` setting, since automodapi uses autosummary
2. Add options `automodapi_imported_members` and `automodsumm_imported_members` to adjust this behavior for only the `automodapi` or `automodsumm` directives, respectively.
3. Add a `:no-imported-members:` option to both the `automodapi` and `automodsumm` directives

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in sphinx_automodapi/automodsumm.py at the cited find_mod_objs call, then read sphinx_automodapi.utils.find_mod_objs and its existing onlylocals argument. Determine how the automodapi and automodsumm directives should expose the requested behavior; done means imported members can be excluded without monkey-patching or hardcoded lists.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.