Docstring Processing

class FilterProcessor(Processor):
    """
    Filter processor removes API objects based on specified criteria.
    
    Attributes:
        expression: Python expression evaluated with variables 'name', 'obj', and 'default()'
                   to determine if object should be kept (default: None)
        documented_only: Only include objects with docstrings (default: True)
        do_not_filter_modules: Never filter out modules (default: False)  
        skip_empty_modules: Remove modules with no remaining members after filtering (default: True)
    """
    expression: Optional[str]
    documented_only: bool
    do_not_filter_modules: bool
    skip_empty_modules: bool
    
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
        """
        Apply filtering rules to remove unwanted API objects.
        
        Args:
            modules: List of modules to filter
            resolver: Optional resolver for cross-references
        """

class CrossrefProcessor(Processor):
    """
    Process cross-references in docstrings and convert them to hyperlinks.
    
    Attributes:
        resolver_v2: Optional resolver for reference resolution (default: None)
    """
    resolver_v2: Optional[ResolverV2]
    
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
        """
        Process cross-references in docstrings.
        
        Args:
            modules: List of modules to process
            resolver: Resolver for converting references to hyperlinks
        """

class GoogleProcessor(Processor):
    """
    Process Google-style docstrings and convert them to Markdown.
    
    Handles sections like Args:, Returns:, Raises:, Yields:, Note:, Example:
    """
    
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
        """
        Convert Google-style docstrings to Markdown format.
        
        Args:
            modules: List of modules to process
            resolver: Optional resolver for cross-references
        """

class SphinxProcessor(Processor):
    """
    Process Sphinx-style docstrings and convert them to Markdown.
    
    Handles reStructuredText directives like :param:, :returns:, :raises:, etc.
    """
    
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
        """
        Convert Sphinx-style docstrings to Markdown format.
        
        Args:
            modules: List of modules to process  
            resolver: Optional resolver for cross-references
        """

class SmartProcessor(Processor):
    """
    Apply smart formatting enhancements to docstrings.
    
    Automatically detects and formats code blocks, lists, and other common
    documentation patterns for improved Markdown output.
    """
    
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
        """
        Apply smart formatting to docstrings.
        
        Args:
            modules: List of modules to process
            resolver: Optional resolver for cross-references  
        """

class PydocmdProcessor(Processor):
    """
    Process Pydoc-Markdown native docstring format.
    
    Handles custom Pydoc-Markdown syntax and formatting extensions.
    """
    
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
        """
        Process Pydoc-Markdown format docstrings.
        
        Args:
            modules: List of modules to process
            resolver: Optional resolver for cross-references
        """

from pydoc_markdown import PydocMarkdown
from pydoc_markdown.contrib.processors.filter import FilterProcessor

# Only include documented public members
processor = FilterProcessor(
    documented_only=True,
    expression="not name.startswith('_')"
)

config = PydocMarkdown(processors=[processor])

from pydoc_markdown.contrib.processors.filter import FilterProcessor

# Complex filtering with custom expression
processor = FilterProcessor(
    expression="not name.startswith('_') and 'deprecated' not in (obj.docstring or '').lower()",
    documented_only=True,
    skip_empty_modules=True
)

from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor

# Enable cross-reference resolution
processor = CrossrefProcessor()

config = PydocMarkdown(processors=[processor])

from pydoc_markdown.contrib.processors.google import GoogleProcessor

# Convert Google-style docstrings
processor = GoogleProcessor()

# Example docstring it processes:
"""
Calculate the area of a rectangle.

Args:
    width (float): The width of the rectangle.
    height (float): The height of the rectangle.

Returns:
    float: The area of the rectangle.

Raises:
    ValueError: If width or height is negative.
"""

from pydoc_markdown.contrib.processors.sphinx import SphinxProcessor

# Convert Sphinx-style docstrings  
processor = SphinxProcessor()

# Example docstring it processes:
"""
Calculate the area of a rectangle.

:param width: The width of the rectangle
:type width: float
:param height: The height of the rectangle  
:type height: float
:returns: The area of the rectangle
:rtype: float
:raises ValueError: If width or height is negative
"""

from pydoc_markdown import PydocMarkdown
from pydoc_markdown.contrib.processors.filter import FilterProcessor
from pydoc_markdown.contrib.processors.google import GoogleProcessor
from pydoc_markdown.contrib.processors.smart import SmartProcessor
from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor

# Comprehensive processor pipeline
config = PydocMarkdown(
    processors=[
        FilterProcessor(
            documented_only=True,
            expression="not name.startswith('_') and default()"
        ),
        GoogleProcessor(),  # Convert Google-style docstrings
        SmartProcessor(),   # Apply smart formatting
        CrossrefProcessor()  # Resolve cross-references
    ]
)

processors:
  # Filter undocumented and private members
  - type: filter
    documented_only: true
    expression: "not name.startswith('_') and default()"
    skip_empty_modules: true
    
  # Convert Google-style docstrings
  - type: google
  
  # Apply smart formatting  
  - type: smart
  
  # Resolve cross-references
  - type: crossref

processors:
  - type: filter
    # Custom expression for complex filtering
    expression: |
      (not name.startswith('_')) and 
      ('deprecated' not in (obj.docstring or '').lower()) and
      (not hasattr(obj, 'decorations') or 
       not any(d.name == 'private' for d in (obj.decorations or []))) and
      default()
    documented_only: true
    do_not_filter_modules: false
    skip_empty_modules: true

# For Google-style docstrings
processors:
  - type: filter
  - type: google
  - type: smart  
  - type: crossref

# For Sphinx-style docstrings  
processors:
  - type: filter
  - type: sphinx
  - type: smart
  - type: crossref

# For mixed formats
processors:
  - type: filter
  - type: google
  - type: sphinx  
  - type: pydocmd
  - type: smart
  - type: crossref

processors = [
    FilterProcessor(),      # 1. Filter content
    GoogleProcessor(),      # 2. Convert docstring format
    SmartProcessor(),       # 3. Apply smart formatting
    CrossrefProcessor()     # 4. Resolve cross-references
]