CLI Tools

def main(argv=None) -> int:
    """
    CLI entry point, returns exit code.
    
    Main command-line interface function that parses arguments,
    dispatches to appropriate subcommands, and handles errors.
    
    Parameters
    ----------
    argv : list of str, optional
        Command-line arguments (defaults to sys.argv[1:])
        
    Returns
    -------
    int
        Exit code (0 for success, non-zero for errors)
        
    Examples
    --------
    >>> from numpydoc.cli import main
    >>> main(['render', 'numpy.array'])
    0
    
    >>> main(['validate', 'numpy.mean'])  
    0
    """

def get_parser() -> argparse.ArgumentParser:
    """
    Return argparse.ArgumentParser for CLI.
    
    Creates and configures the argument parser with all subcommands,
    options, and help text for the numpydoc CLI interface.
    
    Returns
    -------
    argparse.ArgumentParser
        Configured argument parser with subcommands:
        - render: Render docstring to reStructuredText
        - validate: Validate single object docstring  
        - lint: Validate files using AST parsing
        
    Examples
    --------
    >>> parser = get_parser()
    >>> args = parser.parse_args(['render', 'numpy.array'])
    >>> print(args.command)
    'render'
    >>> print(args.import_path)  
    'numpy.array'
    """

def render_object(import_path: str, config=None):
    """
    Test docstring rendering for object.
    
    Loads the specified object, parses its docstring, and renders
    it to reStructuredText format for preview or debugging purposes.
    
    Parameters
    ----------
    import_path : str
        Dotted import path to object (e.g., 'numpy.array', 'scipy.stats.norm')
    config : dict, optional
        Configuration dictionary for rendering options
        
    Examples
    --------
    >>> render_object('numpy.array')  
    # Outputs rendered reStructuredText to stdout
    
    >>> render_object('mymodule.MyClass.method')
    # Renders method docstring with proper formatting
    """

def validate_object(import_path: str):
    """
    Run validation for object.
    
    Performs comprehensive docstring validation for the specified
    object and reports any validation errors found.
    
    Parameters
    ----------
    import_path : str
        Dotted import path to object to validate
        
    Examples
    --------  
    >>> validate_object('numpy.mean')
    # Outputs validation results to stdout
    
    >>> validate_object('scipy.stats.norm.pdf')  
    # Validates specific method docstring
    """

# Basic rendering
numpydoc render numpy.array

# Render class method  
numpydoc render pandas.DataFrame.head

# Render with custom config
numpydoc render --config myconfig.json numpy.fft.fft

# Validate single function
numpydoc validate numpy.mean

# Validate class
numpydoc validate sklearn.linear_model.LinearRegression

# Validate method
numpydoc validate matplotlib.pyplot.plot

# Validate all functions in a file
numpydoc lint src/mymodule.py

# Validate multiple files
numpydoc lint src/*.py

# Validate with specific config  
numpydoc lint --config pyproject.toml src/

# Exclude certain checks
numpydoc lint --ignore GL01,SS01 myfile.py

numpydoc [global-options] <command> [command-options]

Global Options:
  -h, --help     Show help message and exit
  -V, --version  Show program version and exit

numpydoc render [options] <import_path>

Arguments:
  import_path    Dotted path to object (e.g., numpy.array)

Options:
  -c, --config FILE    Configuration file path
  -o, --output FILE    Output file (default: stdout)  
  --format FORMAT      Output format (rst, html, markdown)

numpydoc validate [options] <import_path>

Arguments:
  import_path    Dotted path to object to validate

Options:
  -c, --config FILE    Configuration file path
  --checks CODES       Comma-separated validation check codes
  --ignore CODES       Comma-separated codes to ignore
  --verbose            Show detailed validation information

numpydoc lint [options] <files...>

Arguments:
  files...       Python source files to validate

Options:
  -c, --config FILE    Configuration file (pyproject.toml, setup.cfg)
  --checks CODES       Comma-separated validation check codes  
  --ignore CODES       Comma-separated codes to ignore
  --exclude PATTERNS   File patterns to exclude from validation
  --verbose            Show detailed output
  --quiet              Suppress output except errors

[tool.numpydoc_validation]
checks = ["all", "GL08"]
ignore = ["GL01", "SS01"] 
exclude = [
    "tests/.*",
    ".*/_private.py"
]

override = {"mymodule.legacy_func" = {"all" = false}}

[numpydoc_validation]  
checks = all,GL08
ignore = GL01,SS01
exclude = tests/.*,.*/_private.py

{
  "checks": ["all", "GL08"],
  "ignore": ["GL01", "SS01"],
  "exclude": ["tests/.*", ".*/_private.py"],
  "override": {
    "mymodule.legacy_func": {"all": false}
  }
}

# Render numpy array docstring
$ numpydoc render numpy.array
Create an array.

Parameters
----------
object : array_like
    An array, any object exposing the array interface...
    
Returns  
-------
out : ndarray
    An array object satisfying the specified requirements.

# Validate with specific checks
$ numpydoc validate --checks GL01,SS01,PR01 mymodule.func
GL01: Docstring text (summary) should start in the line immediately after the opening quotes
PR01: Parameters {'x'} not documented

# Ignore certain validation errors
$ numpydoc validate --ignore GL08 mymodule.func

# Validate all Python files in src/
$ numpydoc lint src/
src/module1.py:15: GL01: Docstring text should start immediately after quotes
src/module2.py:42: PR01: Parameters {'param'} not documented  
src/module3.py:89: RT01: No Returns section found

Found 3 validation errors in 3 files.

# Validate with configuration file
$ numpydoc lint --config pyproject.toml src/
Using configuration from pyproject.toml
Checking 15 files...
All docstrings valid!

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: numpydoc-validation
        name: numpydoc docstring validation
        entry: numpydoc lint
        language: system
        files: \.py$
        args: ['--config', 'pyproject.toml']

from numpydoc.cli import main, render_object, validate_object

# Use CLI functions programmatically
exit_code = main(['validate', 'numpy.array'])
print(f"Validation exit code: {exit_code}")

# Direct function calls
render_object('scipy.stats.norm')
validate_object('pandas.DataFrame.head')

# Custom configuration
config = {'validation_checks': {'GL01', 'SS01'}}  
render_object('mymodule.func', config=config)