How to exclude an API member from being processed by numpydoc
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
Context
I need type annotations and this project doesn't support this yet (#196, #356)- I tested out successfully sphinx.ext.napoleon, but that project doesn't provide a validator (crazy, right?), so here I am, awkwardly in the middle of two lovers.
Feature request
Regardless if during Sphinx build or from the pre-commit hook, I would like to specify a list of API members to ignore.
Numpydoc already provides numpydoc_validation_exclude, but that is indeed for validation, not the whole thing.
In fact what I get if I use the following configuration,
extensions = [
"numpydoc",
"sphinx.ext.autodoc",
"sphinx_automodapi.automodapi",
"sphinx.ext.napoleon",
]
napoleon_numpy_docstring = True
numpydoc_show_class_members = False
# Report warnings for all validation checks except those specified after "all"
numpydoc_validation_checks = {"all", "ES01", "SA01", "EX01", "RT02"}
# for why we currently ignore "RT02" see https://github.com/numpy/numpydoc/issues/244
numpydoc_validation_exclude = {
"my_module.greeting",
}
with the following function,
def greeting(name: str) -> str:
"""
Perform a greeting.
Parameters
----------
name
Name to use.
Returns
-------
greeting
The greeting.
"""
greeting = "Hello " + name
return greeting
Is this (see that the Parameters section is doubled)?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Sphinx build and pre-commit paths described in the issue, comparing their behavior with the existing numpydoc_validation_exclude configuration. Determine how an API-member exclusion list should apply to the shown greeting example; done means the member is skipped during processing in both contexts without changing validation-only exclusions.
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
- 35/100