Configuration Options

class PythonConfig:
    """Main configuration class for the Python handler."""
    options: PythonOptions
    
class PythonInputConfig:
    """Input configuration class for Python handler settings."""
    options: PythonInputOptions
    
class PythonOptions(PythonInputOptions):
    """Options configuration class with all handler options."""
    
class PythonInputOptions:
    """Input options class for Python handler configuration."""
    
    # Core options
    docstring_style: str = "google"
    show_source: bool = False
    show_root_heading: bool = False
    show_root_toc_entry: bool = True
    show_root_full_path: bool = True
    show_root_members_full_path: bool = False
    show_object_full_path: bool = False
    show_category_heading: bool = False
    show_symbol_type_heading: bool = False
    show_symbol_type_toc: bool = False
    
    # Collection options
    allow_inspection: bool = True
    force_inspection: bool = False
    find_stubs_package: bool = False
    preload_modules: list[str] = field(default_factory=list)
    
    # Member organization
    members_order: Order = "alphabetical"
    filters: list[str] = field(default_factory=lambda: ["!^_[^_]"])
    group_by_category: bool = True
    show_submodules: bool = False
    
    # Heading options
    heading_level: int = 2
    
    # Signature options
    show_signature: bool = True
    show_signature_annotations: bool = False
    signature_crossrefs: bool = False
    separate_signature: bool = False
    annotations_path: Literal["brief", "source", "full"] = "brief"
    modernize_annotations: bool = False
    show_signature_type_parameters: bool = False
    
    # Docstring options
    docstring_style: str = "google"
    docstring_options: PerStyleOptions = field(default_factory=PerStyleOptions)
    merge_init_into_class: bool = False
    show_if_no_docstring: bool = False
    show_docstring_attributes: bool = True
    show_docstring_functions: bool = True
    show_docstring_classes: bool = True
    show_docstring_modules: bool = True
    show_docstring_description: bool = True
    show_docstring_examples: bool = True
    show_docstring_other_parameters: bool = True
    show_docstring_parameters: bool = True
    show_docstring_raises: bool = True
    show_docstring_receives: bool = True
    show_docstring_returns: bool = True
    show_docstring_warns: bool = True
    show_docstring_yields: bool = True
    
    # Display options
    show_overloads: bool = True
    show_attribute_values: bool = True
    show_bases: bool = True
    show_labels: bool = True
    show_inheritance_diagram: bool = False
    show_if_no_docstring: bool = False
    
    # Cross-reference options
    backlinks: Literal["flat", "tree", False] = False
    relative_crossrefs: bool = False
    scoped_crossrefs: bool = False
    skip_local_inventory: bool = False
    
    # Inheritance options
    inherited_members: bool = False
    
    # Line length options  
    line_length: int = 60
    
    # Advanced options
    docstring_section_style: Literal["table", "list", "spacy"] = "table"
    extensions: list[str | dict[str, Any]] = field(default_factory=list)
    parameter_headings: bool = False
    type_parameter_headings: bool = False
    unwrap_annotated: bool = False
    overloads_only: bool = False
    toc_label: str = ""
    extra: dict[str, Any] = field(default_factory=dict)
    
    # Summary options
    summary: SummaryOption = field(default_factory=SummaryOption)

from mkdocstrings_handlers.python import PythonConfig, PythonOptions

# Create configuration with custom options
config = PythonConfig(
    options=PythonOptions(
        docstring_style="numpy",
        show_source=True,
        show_root_heading=True,
        members_order="source",
        filters=["!^_", "!^__.*__$"],
        line_length=88,
        show_signature_annotations=True
    )
)

class GoogleStyleOptions:
    """Configuration options for Google-style docstrings."""
    
    ignore_init_summary: bool = False
    returns_multiple_items: bool = True
    returns_named_value: bool = True  
    returns_type_in_property_summary: bool = False
    receives_multiple_items: bool = True
    receives_named_value: bool = True
    warn_unknown_params: bool = True
    trim_doctest_flags: bool = True
    warn_missing_types: bool = True
    warnings: bool = True
    
class NumpyStyleOptions:
    """Configuration options for NumPy-style docstrings."""
    
    ignore_init_summary: bool = False
    returns_multiple_items: bool = True
    returns_named_value: bool = True
    receives_multiple_items: bool = True  
    receives_named_value: bool = True
    warn_unknown_params: bool = True
    trim_doctest_flags: bool = True
    warn_missing_types: bool = True
    warnings: bool = True
    
class SphinxStyleOptions:
    """Configuration options for Sphinx-style docstrings."""
    
    warn_unknown_params: bool = True
    warn_missing_types: bool = True
    warnings: bool = True
    
class PerStyleOptions:
    """Per-style configuration options container."""
    
    google: GoogleStyleOptions = field(default_factory=GoogleStyleOptions)
    numpy: NumpyStyleOptions = field(default_factory=NumpyStyleOptions)
    sphinx: SphinxStyleOptions = field(default_factory=SphinxStyleOptions)
    
class AutoStyleOptions:
    """Automatic style detection options."""
    
    method: Literal["heuristics", "max_sections"] = "heuristics"
    style_order: list[str] = field(default_factory=lambda: ["sphinx", "google", "numpy"])
    default: str | None = None
    per_style_options: PerStyleOptions = field(default_factory=PerStyleOptions)

from mkdocstrings_handlers.python import (
    PythonOptions, 
    PerStyleOptions,
    GoogleStyleOptions,
    NumpyStyleOptions
)

# Configure style-specific options
docstring_options = PerStyleOptions(
    google=GoogleStyleOptions(
        ignore_init_summary=True,
        returns_multiple_items=False
    ),
    numpy=NumpyStyleOptions(
        warn_unknown_params=False
    )
)

options = PythonOptions(
    docstring_style="google",
    docstring_options=docstring_options
)

class Inventory:
    """Configuration for cross-reference inventories."""
    
    url: str
    """URL to the inventory file."""
    
    base_url: str | None = None
    """Base URL for cross-references."""
    
    domains: list[str] = field(default_factory=lambda: ["py"])
    """Documentation domains to include."""
    
    @property
    def _config(self) -> dict[str, Any]:
        """Internal configuration dictionary."""

from mkdocstrings_handlers.python import Inventory

# Configure external inventories
numpy_inventory = Inventory(base_url="https://numpy.org/doc/stable/")
pandas_inventory = Inventory(base_url="https://pandas.pydata.org/docs/")

class SummaryOption:
    """Options for docstring summary handling."""
    
    # Summary configuration properties

from mkdocstrings_handlers.python import SummaryOption, PythonOptions

summary_config = SummaryOption()

options = PythonOptions(
    summary=summary_config,
    show_docstring_description=True
)