"""Sphinx extension for auto-generating API documentation."""

from __future__ import annotations

import fnmatch
import re
from pathlib import Path
from typing import TYPE_CHECKING

from sphinx._cli.util.colour import bold
from sphinx.ext.apidoc._generate import create_modules_toc_file, recurse_tree
from sphinx.ext.apidoc._shared import (
    LOGGER,
    ApidocDefaults,
    ApidocOptions,
    _remove_old_files,
)
from sphinx.locale import __

if TYPE_CHECKING:
    from collections.abc import Collection, Sequence
    from typing import Any

    from sphinx.application import Sphinx

_BOOL_KEYS = frozenset({
    'follow_links',
    'separate_modules',
    'include_private',
    'no_headings',
    'module_first',
    'implicit_namespaces',
})
_ALLOWED_KEYS = _BOOL_KEYS | frozenset({
    'path',
    'destination',
    'exclude_patterns',
    'automodule_options',
    'max_depth',
})


def run_apidoc(app: Sphinx) -> None:
    """Run the apidoc extension."""
    defaults = ApidocDefaults.from_config(app.config)
    apidoc_modules: Sequence[dict[str, Any]] = app.config.apidoc_modules
    srcdir: Path = app.srcdir
    confdir: Path = app.confdir

    LOGGER.info(bold(__('Running apidoc')))

    module_options: dict[str, Any]
    for i, module_options in enumerate(apidoc_modules):
        _run_apidoc_module(
            i,
            options=module_options,
            defaults=defaults,
            srcdir=srcdir,
            confdir=confdir,
        )


def _run_apidoc_module(
    i: int,
    *,
    options: dict[str, Any],
    defaults: ApidocDefaults,
    srcdir: Path,
    confdir: Path,
) -> None:
    """Run apidoc for a single module."""
    args = _parse_module_options(
        i, options=options, defaults=defaults, srcdir=srcdir, confdir=confdir
    )
    if args is None:
        return

    exclude_patterns_compiled: list[re.Pattern[str]] = [
        re.compile(fnmatch.translate(exclude)) for exclude in args.exclude_pattern
    ]

    written_files, modules = recurse_tree(
        args.module_path, exclude_patterns_compiled, args, args.template_dir
    )
    if args.toc_file:
        written_files.append(
            create_modules_toc_file(modules, args, args.toc_file, args.template_dir)
        )
    if args.remove_old:
        _remove_old_files(written_files, args.dest_dir, args.suffix)


def _parse_module_options(
    i: int,
    *,
    options: dict[str, Any],
    defaults: ApidocDefaults,
    srcdir: Path,
    confdir: Path,
) -> ApidocOptions | None:
    if not isinstance(options, dict):
        LOGGER.warning(__('apidoc_modules item %i must be a dict'), i, type='apidoc')
        return None

    # module path should be absolute or relative to the conf directory
    try:
        path = Path(options['path'])
    except KeyError:
        LOGGER.warning(
            __("apidoc_modules item %i must have a 'path' key"), i, type='apidoc'
        )
        return None
    except TypeError:
        LOGGER.warning(
            __("apidoc_modules item %i 'path' must be a string"), i, type='apidoc'
        )
        return None
    module_path = confdir / path
    if not module_path.is_dir():
        LOGGER.warning(
            __("apidoc_modules item %i 'path' is not an existing folder: %s"),
            i,
            module_path,
            type='apidoc',
        )
        return None

    # destination path should be relative to the source directory
    try:
        destination = Path(options['destination'])
    except KeyError:
        LOGGER.warning(
            __("apidoc_modules item %i must have a 'destination' key"),
            i,
            type='apidoc',
        )
        return None
    except TypeError:
        LOGGER.warning(
            __("apidoc_modules item %i 'destination' must be a string"),
            i,
            type='apidoc',
        )
        return None
    if destination.is_absolute():
        LOGGER.warning(
            __("apidoc_modules item %i 'destination' should be a relative path"),
            i,
            type='apidoc',
        )
        return None
    dest_path = srcdir / destination
    try:
        dest_path.mkdir(parents=True, exist_ok=True)
    except OSError as exc:
        LOGGER.warning(
            __('apidoc_modules item %i cannot create destination directory: %s'),
            i,
            exc.strerror,
            type='apidoc',
        )
        return None

    # exclude patterns should be absolute or relative to the conf directory
    exclude_patterns: list[str] = [
        str(confdir / pattern)
        for pattern in _check_collection_of_strings(
            i, options, key='exclude_patterns', default=defaults.exclude_patterns
        )
    ]

    # TODO template_dir

    max_depth = defaults.max_depth
    if 'max_depth' in options:
        if not isinstance(options['max_depth'], int):
            LOGGER.warning(
                __("apidoc_modules item %i '%s' must be an int"),
                i,
                'max_depth',
                type='apidoc',
            )
        else:
            max_depth = options['max_depth']

    bool_options: dict[str, bool] = {}
    for key in sorted(_BOOL_KEYS):
        if key not in options:
            bool_options[key] = getattr(defaults, key)
        elif not isinstance(options[key], bool):
            LOGGER.warning(
                __("apidoc_modules item %i '%s' must be a boolean"),
                i,
                key,
                type='apidoc',
            )
            bool_options[key] = getattr(defaults, key)
        else:
            bool_options[key] = options[key]

    # TODO per-module automodule_options
    automodule_options = frozenset(
        _check_collection_of_strings(
            i, options, key='automodule_options', default=defaults.automodule_options
        )
    )

    if diff := options.keys() - _ALLOWED_KEYS:
        LOGGER.warning(
            __('apidoc_modules item %i has unexpected keys: %s'),
            i,
            ', '.join(sorted(diff)),
            type='apidoc',
        )

    return ApidocOptions(
        dest_dir=dest_path,
        module_path=module_path,
        exclude_pattern=exclude_patterns,
        max_depth=max_depth,
        quiet=True,
        follow_links=bool_options['follow_links'],
        separate_modules=bool_options['separate_modules'],
        include_private=bool_options['include_private'],
        no_headings=bool_options['no_headings'],
        module_first=bool_options['module_first'],
        implicit_namespaces=bool_options['implicit_namespaces'],
        automodule_options=automodule_options,
        header=module_path.name,
    )


def _check_collection_of_strings(
    index: int,
    options: dict[str, Any],
    *,
    key: str,
    default: Collection[str],
) -> Collection[str]:
    """Check that a key's value is a collection of strings in the options.

    :returns: The value of the key, or None if invalid.
    """
    if key not in options:
        return default
    if not isinstance(options[key], (list, tuple, set, frozenset)):
        LOGGER.warning(
            __("apidoc_modules item %i '%s' must be a sequence"),
            index,
            key,
            type='apidoc',
        )
        return default
    for item in options[key]:
        if not isinstance(item, str):
            LOGGER.warning(
                __("apidoc_modules item %i '%s' must contain strings"),
                index,
                key,
                type='apidoc',
            )
            return default
    return options[key]