astral-sh / astral-sh/ruff

pydocstyle: Ignore matching functions

Open
#7,401 4 comments 9 reactions 0 assignees View on GitHub
docstring needs-decision
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.