from ...decorators import LogLevels as LogLevels, handle_error as handle_error
from ...io.path import clean_path as clean_path, super_open as super_open
from ...print.message import info as info, warning as warning
from .common import check_base_dependencies as check_base_dependencies, download_asset as download_asset, generate_redirect_html as generate_redirect_html, generate_version_selector as generate_version_selector, get_versions_from_github as get_versions_from_github
from collections.abc import Callable as Callable

def get_zensical_config_content(project: str, project_dir: str, docs_dir: str, site_dir: str, author: str, current_version: str, copyright: str, html_logo: str, html_favicon: str, github_user: str = '', github_repo: str = '', version_list: list[str] | None = None, skip_undocumented: bool = True, api_pages: list[tuple[str, str]] | None = None) -> str:
    """ Get the content of the Zensical configuration file (zensical.toml).

\tArgs:
\t\tproject           (str):              Name of the project
\t\tproject_dir       (str):              Path to the project directory
\t\tdocs_dir          (str):              Path to the docs source directory (relative to root)
\t\tsite_dir          (str):              Path to the build output directory (relative to root)
\t\tauthor            (str):              Author of the project
\t\tcurrent_version   (str):              Current version
\t\tcopyright         (str):              Copyright information
\t\thtml_logo         (str):              Path to the logo image (relative to docs_dir)
\t\thtml_favicon      (str):              Path to the favicon image (relative to docs_dir)
\t\tgithub_user       (str):              GitHub username
\t\tgithub_repo       (str):              GitHub repository name
\t\tversion_list      (list[str] | None): List of versions. Defaults to None
\t\tskip_undocumented (bool):             Whether to skip undocumented members. Defaults to True
\t\tapi_pages         (list[tuple[str, str]] | None): List of (module_name, md_filename) tuples for nav

\tReturns:
\t\tstr: Content of the Zensical configuration file (TOML)
\t"""
def generate_index_md(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str, int], list[str]] = ..., recent_minor_versions: int = 2) -> None:
    """ Generate ``index.md`` from README.md content.

\tThis keeps the README content as Markdown and creates the home page for the
\tZensical documentation. Navigation to API docs is handled by the Zensical
\tconfig (nav or auto-discovery).

\tArgs:
\t\treadme_path            (str): Path to the README.md file
\t\tindex_path             (str): Path where index.md should be created
\t\tproject                (str): Name of the project
\t\tgithub_user            (str): GitHub username
\t\tgithub_repo            (str): GitHub repository name
\t\tget_versions_function  (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
\t\trecent_minor_versions  (int): Number of recent minor versions to show all patches for. Defaults to 2
\t"""
def generate_api_pages(api_dir: str, project: str, project_dir: str) -> list[tuple[str, str]]:
    """ Walk the project directory and generate Markdown pages with ``:::`` directives
\tfor mkdocstrings API documentation.

\tArgs:
\t\tapi_dir      (str): Directory where API markdown pages should be written
\t\tproject      (str): Name of the project (package name)
\t\tproject_dir  (str): Path to the project directory (Python package root)

\tReturns:
\t\tlist[tuple[str, str]]: List of (module_name, md_filename) tuples
\t"""
def generate_documentation(config_path: str, root_path: str) -> None:
    """ Generate documentation using Zensical.

\tArgs:
\t\tconfig_path (str): Path to the zensical.toml configuration file
\t\troot_path   (str): Root path of the project (working directory for the build)
\t"""
def zensical_docs(root_path: str, project: str, project_dir: str = '', author: str = 'Author', copyright: str = '2025, Author', html_logo: str = '', html_favicon: str = '', html_theme: str = '', github_user: str = '', github_repo: str = '', version: str | None = None, skip_undocumented: bool = True, recent_minor_versions: int = 2, get_versions_function: Callable[[str, str, int], list[str]] = ..., generate_index_function: Callable[..., None] = ..., generate_api_pages_function: Callable[..., list[tuple[str, str]]] = ..., generate_docs_function: Callable[..., None] = ..., generate_redirect_function: Callable[[str], None] = ..., get_config_content_function: Callable[..., str] = ...) -> None:
    ''' Update the documentation using Zensical and mkdocstrings.

\tArgs:
\t\troot_path                    (str): Root path of the project
\t\tproject                      (str): Name of the project
\t\tproject_dir                  (str): Path to the project directory (to be used with generate_docs_function)
\t\tauthor                       (str): Author of the project
\t\tcopyright                    (str): Copyright information
\t\thtml_logo                    (str): URL or path to the logo image
\t\thtml_favicon                 (str): URL or path to the favicon image
\t\thtml_theme                   (str): Unused (kept for backward compatibility)
\t\tgithub_user                  (str): GitHub username
\t\tgithub_repo                  (str): GitHub repository name
\t\tversion                      (str | None): Version to build documentation for (e.g. "1.0.0", defaults to "latest")
\t\tskip_undocumented            (bool): Whether to skip undocumented members. Defaults to True
\t\trecent_minor_versions        (int): Number of recent minor versions to show all patches for. Defaults to 2

\t\tget_versions_function        (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
\t\tgenerate_index_function      (Callable[..., None]): Function to generate index.md
\t\tgenerate_api_pages_function  (Callable[..., list[tuple[str, str]]]): Function to generate API pages
\t\tgenerate_docs_function       (Callable[..., None]): Function to generate documentation
\t\tgenerate_redirect_function   (Callable[[str], None]): Function to create redirect file
\t\tget_config_content_function  (Callable[..., str]): Function to get Zensical config content
\t'''
