Feature Request: Support for Standalone numpydoc.toml Configuration File

[vadivelselvaraj]

Problem Statement

Currently, numpydoc requires configuration to be present in either pyproject.toml or setup.cfg files within each Python package. This creates challenges in monorepo setups where multiple Python packages need to share common docstring validation rules and configurations.

Use Case: Monorepo Setup

In a monorepo with multiple Python packages, maintaining consistent docstring standards across all packages becomes challenging. Consider this structure:

monorepo/
├── resources/
│   ├── numpydoc.toml       # Proposed centralized config
│   └── ruff.toml          # Similar to how ruff handles centralized config
├── libs/
│   ├── lib1/
│   │   ├── pyproject.toml  # Package-specific config with poe tasks
│   │   └── src/
│   ├── lib2/
│   │   ├── pyproject.toml
│   │   └── src/
│   └── lib3/
│       ├── pyproject.toml
│       └── src/

Example Package Configuration

# libs/lib1/pyproject.toml
[tool.numpydoc_validation]
extends = "../../resources/numpydoc.toml"

[tool.poe.tasks.validate-docs]
help = "Run docstring validation via numpydoc"
script = "numpydoc lint --config=../../resources/numpydoc.toml src/**/*.py"

This setup allows:

1. Centralized configuration in resources/ directory (similar to how ruff handles its configuration)
2. Easy reference to shared config files from package-specific tasks
3. Consistent validation across all packages using poethepoet tasks

Proposed Solution

Add support for a standalone numpydoc.toml configuration file that can be referenced from multiple packages, with the ability to override settings locally when needed.

Configuration Format

# numpydoc.toml
[tool.numpydoc_validation]
checks = [
    "all",   # report on all checks, except the below
    "EX01",
    "SA01",
    "ES01",
]
# remember to use single quotes for regex in TOML
exclude = [  # don't report on objects that match any of these regex
    '\.undocumented_method$',
    '\.__repr__$',
]
override_SS05 = [  # override SS05 to allow docstrings starting with these words
    '^Process ',
    '^Assess ',
    '^Access ',
]

# Optional: Allow packages to extend this config
allow_local_override = true

Local Package Override (in pyproject.toml)

[tool.numpydoc_validation]
# Reference the shared config
extends = "../resources/numpydoc.toml"

# Override specific settings
exclude = [
    '\._internal_',  # Additional package-specific exclusions
]

Benefits

1. Centralized Configuration:

   • Single source of truth for docstring standards
   • Easier maintenance and updates
   • Consistent validation across packages

2. Flexibility:

   • Support for local overrides when needed
   • Backward compatible with existing setups
   • Similar to other tools like ruff, black, etc.

3. Improved Monorepo Support:

   • Better handling of multi-package repositories
   • Reduced configuration duplication
   • Easier to maintain consistency

Technical Implementation

1. Add support for standalone numpydoc.toml file
2. Implement configuration inheritance:

   # Configuration precedence (highest to lowest):
   # 1. Command line arguments
   # 2. Local pyproject.toml/setup.cfg
   # 3. Referenced numpydoc.toml
   # 4. Default settings

3. Add new CLI and pre-commit hook parameters:

   # CLI
   numpydoc lint --config_file path/to/numpydoc.toml
   
   # Pre-commit
   - repo: https://github.com/numpy/numpydoc
     rev: <version>
     hooks:
       - id: numpydoc-validation
         args: ["--config_file=resources/numpydoc.toml"]

Similar Implementations

• Ruff: Uses standalone ruff.toml with inheritance support
• Black: Global config support in pyproject.toml
• Flake8: Multiple config file support with inheritance

Backward Compatibility

The feature maintains backward compatibility:

• Existing pyproject.toml/setup.cfg continue to work
• New config_file parameter is optional
• Default behavior unchanged if no external config specified

Would love to hear thoughts on this approach and any suggestions for improvement.

[amirhessam88]

This can be a nice feature since I personally do not use the pyproject.toml override part and I abstract out all the resource files that are needed for formatting/linting/... in a separate directory; this is very true for a mono-repo project with tons of pyproject.toml; In this way, we do not copy/paste the same code over and over