astropy / astropy/sphinx-automodapi
Add option to exclude imported members
- 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