0
# numpydoc
1

2
numpydoc is a Sphinx extension for handling docstrings in NumPy format. It provides comprehensive tools for parsing, validating, and rendering NumPy-style docstrings, along with command-line utilities and Git hooks for automated docstring validation.
3

4
## Package Information
5

6
- **Package**: `numpydoc`
7
- **Version**: 1.9.0
8
- **Python**: 3.9+
9
- **Install**: `pip install numpydoc`
10
- **Repository**: https://github.com/numpy/numpydoc
11

12
### Dependencies
13
- **Required**: `sphinx>=6`, `tomli>=1.1.0` (Python <3.11)
14
- **Development**: pytest, matplotlib, pre-commit
15

16
## Core Imports
17

18
```python
19
# Main Sphinx extension setup
20
from numpydoc import setup
21

22
# CLI functionality  
23
from numpydoc.cli import main, get_parser, render_object, validate_object
24

25
# Core Sphinx extension
26
from numpydoc.numpydoc import (
27
    setup, mangle_docstrings, mangle_signature, 
28
    NumpyPythonDomain, NumpyCDomain
29
)
30

31
# Docstring parsing
32
from numpydoc.docscrape import (
33
    NumpyDocString, FunctionDoc, ClassDoc, ObjDoc, 
34
    get_doc_object, Reader
35
)
36

37
# Sphinx integration
38
from numpydoc.docscrape_sphinx import (
39
    SphinxDocString, SphinxFunctionDoc, SphinxClassDoc, 
40
    SphinxObjDoc, get_doc_object
41
)
42

43
# Validation
44
from numpydoc.validate import Validator, validate
45

46
# Cross-referencing
47
from numpydoc.xref import make_xref
48

49
# Git hooks
50
from numpydoc.hooks.validate_docstrings import run_hook, parse_config
51
```
52

53
## Basic Usage
54

55
### Sphinx Extension Setup
56

57
Add numpydoc to your Sphinx configuration:
58

59
```python
60
# conf.py
61
extensions = ['numpydoc']
62

63
# Configuration options
64
numpydoc_use_plots = False
65
numpydoc_show_class_members = True
66
numpydoc_validation_checks = {'all', 'GL08'}
67
```
68

69
### Command Line Usage
70

71
```bash
72
# Render docstring to reStructuredText
73
numpydoc render numpy.array
74

75
# Validate single object docstring  
76
numpydoc validate numpy.mean
77

78
# Validate files using AST parsing
79
numpydoc lint src/mymodule.py
80
```
81

82
## Capabilities
83

84
### [Sphinx Extension](./sphinx-extension.md)
85
Core Sphinx extension functionality for processing NumPy-style docstrings during documentation builds.
86

87
```python { .api }
88
def setup(app, *args, **kwargs):
89
    """Main Sphinx extension setup function."""
90
    ...
91

92
def mangle_docstrings(app, what, name, obj, options, lines):
93
    """Process docstrings during Sphinx build."""
94
    ...
95
```
96

97
### [Docstring Parsing](./docstring-parsing.md) 
98
Comprehensive parsing capabilities for NumPy docstring format with section handling and dictionary-like access.
99

100
```python { .api }
101
class NumpyDocString(Mapping):
102
    """Base docstring parser with dictionary-like interface."""
103
    
104
    def __getitem__(self, key: str) -> List[str]:
105
        """Access docstring sections by name."""
106
        ...
107

108
def get_doc_object(obj, what=None, doc=None, config=None, **kwargs):
109
    """Factory function for creating appropriate docstring parsers."""
110
    ...
111
```
112

113
### [Validation](./validation.md)
114
Extensive validation rules with configurable error codes for ensuring docstring quality and consistency.
115

116
```python { .api }
117
class Validator:
118
    """Main docstring validation class with extensive validation methods."""
119
    
120

121
def validate(obj_name, validator_cls=None, **validator_kwargs):
122
    """Validate docstring for given object name."""
123
    ...
124
```
125

126
### [CLI Tools](./cli-tools.md)
127
Command-line interface for rendering and validation with support for multiple output formats.
128

129
```python { .api }
130
def main(argv=None) -> int:
131
    """CLI entry point, returns exit code."""
132
    ...
133

134
def render_object(import_path: str, config=None):
135
    """Test docstring rendering for object."""
136
    ...
137

138
def validate_object(import_path: str):
139
    """Run validation for object."""
140
    ...
141
```
142

143
### [Git Hooks](./hooks.md)
144
Pre-commit integration for automated docstring validation with configurable rules and project detection.
145

146
```python { .api }
147
def run_hook(files, config=None, ignore=None):
148
    """Main hook function for pre-commit validation."""
149
    ...
150

151
def parse_config(dir_path=None):
152
    """Parse validation config from pyproject.toml/setup.cfg."""
153
    ...
154
```
155

156
## Package Constants
157

158
```python { .api }
159
__version__: str = "1.9.0"
160
"""Package version string."""
161

162
HASH_LEN: int = 12
163
"""Length for reference hash generation."""
164

165
DEDUPLICATION_TAG: str = "<!-- numpydoc_validation -->"
166
"""Tag for processed docstring identification."""
167

168
DEFAULT_LINKS: Dict[str, str]
169
"""
170
Default cross-reference mappings for common Python types.
171

172
Dictionary mapping type names to Sphinx cross-reference roles for
173
automatic linking of parameter and return types in documentation.
174
Includes standard Python types like 'str', 'int', 'list', 'dict', etc.
175
"""
176
```
177

178
## Configuration Options
179

180
numpydoc provides 13 Sphinx configuration values for customizing behavior:
181

182
- `numpydoc_use_plots` - Enable plot directive processing
183
- `numpydoc_show_class_members` - Show class members in documentation  
184
- `numpydoc_show_inherited_class_members` - Show inherited members
185
- `numpydoc_class_members_toctree` - Generate TOC for class members
186
- `numpydoc_citation_re` - Regular expression for citation detection
187
- `numpydoc_attributes_as_param_list` - Format attributes as parameters
188
- `numpydoc_xref_param_type` - Enable parameter type cross-references
189
- `numpydoc_xref_aliases` - Custom type alias mappings
190
- `numpydoc_xref_ignore` - Types to ignore for cross-referencing
191
- `numpydoc_validation_checks` - Validation rules to apply
192
- `numpydoc_validation_exclude` - Objects to exclude from validation
193
- `numpydoc_validation_overrides` - Override validation rules per object
194

195
## Sub-Documentation
196

197
- [Sphinx Extension](./sphinx-extension.md) - Core Sphinx extension functionality
198
- [Docstring Parsing](./docstring-parsing.md) - Docstring parsing capabilities  
199
- [Validation](./validation.md) - Docstring validation functionality
200
- [CLI Tools](./cli-tools.md) - Command-line interface
201
- [Git Hooks](./hooks.md) - Git hooks for pre-commit validation