Flake8 Plugin Integration

class Plugin:
    """
    Flake8 plugin entry point for pydoclint docstring validation.
    
    Provides seamless integration with flake8's linting workflow,
    adding DOC error codes for comprehensive docstring validation.
    """
    
    name: str  # Plugin name 'pydoclint'
    version: str  # Plugin version from package metadata
    
    def __init__(self, tree: ast.AST) -> None:
        """
        Initialize plugin with AST tree.
        
        Parameters:
        - tree: Parsed AST tree of Python source code to analyze
        """

    @classmethod
    def add_options(cls, parser: Any) -> None:
        """
        Add pydoclint-specific options to flake8 argument parser.
        
        Registers all pydoclint configuration options as flake8 command-line
        arguments, enabling configuration through flake8's standard mechanisms.
        
        Parameters:
        - parser: Flake8 argument parser to add options to
        
        Options added:
        - --style: Docstring style (numpy/google/sphinx)
        - --arg-type-hints-in-signature: Require type hints in signatures
        - --arg-type-hints-in-docstring: Require type hints in docstrings
        - --check-arg-order: Validate argument order consistency
        - --skip-checking-short-docstrings: Skip short summary-only docstrings
        - --skip-checking-raises: Skip raises section validation
        - --allow-init-docstring: Allow both __init__ and class docstrings
        - --check-return-types: Validate return type consistency
        - --check-yield-types: Validate yield type consistency
        - --ignore-underscore-args: Ignore underscore arguments
        - --ignore-private-args: Ignore private arguments
        - --check-class-attributes: Validate class attributes
        - --should-document-private-class-attributes: Document private class attrs
        - --treat-property-methods-as-class-attributes: Treat @property as class attrs
        - --require-return-section-when-returning-nothing: Require return for None
        - --require-yield-section-when-yielding-nothing: Require yields for None
        - --only-attrs-with-ClassVar-are-treated-as-class-attrs: ClassVar attrs only
        - --should-document-star-arguments: Document *args/**kwargs
        - --should-declare-assert-error-if-assert-statement-exists: AssertionError for asserts
        - --check-style-mismatch: Validate style consistency
        - --check-arg-defaults: Validate default values in type hints
        """

    @classmethod
    def parse_options(cls, options: Any) -> None:
        """
        Parse and store flake8 options for pydoclint configuration.
        
        Processes options provided by flake8 and stores them as class
        attributes for use during linting execution.
        
        Parameters:
        - options: Parsed options object from flake8
        """

    def run(self) -> Generator[tuple[int, int, str, Any], None, None]:
        """
        Run the linter and yield violation information.
        
        Executes pydoclint analysis on the provided AST tree and yields
        violation information in flake8's expected format.
        
        Returns:
        Generator yielding tuples of:
        - line: Line number of violation
        - col_offset: Column offset of violation
        - message: Formatted error message with DOC code
        - type: Plugin class type
        
        Raises:
        ValueError: If deprecated options are used or invalid style specified
        """

@classmethod
def _bool(cls, optionName: str, optionValue: str) -> bool:
    """
    Parse string boolean values from flake8 configuration.
    
    Parameters:
    - optionName: Name of the option for error reporting
    - optionValue: String value ('True' or 'False')
    
    Returns:
    bool: Parsed boolean value
    
    Raises:
    ValueError: If optionValue is not 'True' or 'False'
    """

# Install with flake8 support
pip install pydoclint[flake8]

# Run flake8 with pydoclint DOC codes
flake8 --select=DOC src/

# Combine with other linters
flake8 --select=E,W,F,DOC src/

# Show only pydoclint violations
flake8 --select=DOC src/

[flake8]
select = DOC
style = numpy
exclude = .git,__pycache__,tests/
arg-type-hints-in-signature = True
check-class-attributes = True
check-return-types = True

[tool.flake8]
select = ["DOC"]
style = "google"
exclude = [".git", "__pycache__", "tests/"]
arg-type-hints-in-docstring = true
check-yield-types = true
ignore-underscore-args = true

# Use with pre-commit
# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: flake8-docstring
      name: flake8 docstring linting
      entry: flake8 --select=DOC
      language: system
      types: [python]

# Combine with mypy and other tools
flake8 --select=E,W,F,DOC --statistics src/
mypy src/
black --check src/

# Ignore specific DOC codes
flake8 --select=DOC --ignore=DOC101,DOC102 src/

# Focus on specific violation categories
flake8 --select=DOC1,DOC2 src/  # Only argument and return issues
flake8 --select=DOC3 src/       # Only class-related issues
flake8 --select=DOC4 src/       # Only yield-related issues
flake8 --select=DOC5 src/       # Only raises-related issues

# Use flake8 per-file ignores
[flake8]
per-file-ignores =
    __init__.py: DOC
    tests/*: DOC101,DOC102
    legacy/*: DOC