pydocstyle: Ignore matching functions
- Dominant language
- Rust
- Stars
- 49.6k
- Forks
- 2.4k
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 458
Description
## Summary
I would like the ability to ignore functions matching a pattern for `pydocstyle`. This is primarily motivated by the definition of test functions which, due to their number and straightforwardness, need not be documented in general. This would be especially useful in cases where some other functions within the same file need to be documented.
I'm thinking this could be achieved as follows:
```toml
[tool.ruff.pydocstyle]
ignore = [
"test_*",
"*_test"
]
```
## Motivation
Requiring all publicly facing functions to have documentation I think can be a very good; however, I am finding myself writing a test suite and this requirement is becoming a hinderance in cases where I want some functions documented, and some are just test functions.
For example, when defining [pytest fixtures](https://docs.pytest.org/en/latest/explanation/fixtures.html), I would prefer to require these functions to be documented properly; while simultaneously allowing test functions to remain undocumented.
## Alternatives
### Ignore Rule in directory / files
One option is to simply adjust the ignored rules for the tests directory,
```toml
extend = "../pyproject.toml"
ignore = ["D103"]
```
or making use of `per-file-ignores`.
This option is not ideal in cases were some code within these files/directories should be documented (as explained above).
### Per-line Ignore
It is of course possible to add `# noqa: D103` after each test function. This achieves the desired results at the cost of being very verbose.
Contributor guide
Research direction
Start by tracing Ruff's pydocstyle implementation and configuration handling, then inspect the existing tests for pydocstyle rules and function-name matching. Define how configured patterns apply to test functions while leaving other functions subject to documentation checks, and add coverage showing the TOML configuration works alongside existing per-file and per-line ignores.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100