import json
import logging
import os
import re
import shutil
import subprocess
from html.parser import HTMLParser
from http.server import HTTPServer, SimpleHTTPRequestHandler
from multiprocessing import Pool
from pathlib import Path
from typing import Any

import typer
import yaml
from jinja2 import Template
from ruff.__main__ import find_ruff_bin
from slugify import slugify as py_slugify

logging.basicConfig(level=logging.INFO)

SUPPORTED_LANGS = {
    "de",
    "en",
    "es",
    "fr",
    "ja",
    "ko",
    "pt",
    "ru",
    "tr",
    "uk",
    "zh",
    "zh-hant",
}


app = typer.Typer()

mkdocs_name = "mkdocs.yml"

non_translated_sections = (
    f"reference{os.sep}",
    "release-notes.md",
    "fastapi-people.md",
    "external-links.md",
    "newsletter.md",
    "management-tasks.md",
    "management.md",
    "contributing.md",
    "translations.md",
)

docs_path = Path("docs")
en_docs_path = Path("docs/en")
en_config_path: Path = en_docs_path / mkdocs_name
site_path = Path("site").absolute()
zensical_src_path = Path("site_zensical_src").absolute()

header_pattern = re.compile(r"^(#{1,6}) (.+?)(?:\s*\{\s*(#.*)\s*\})?\s*$")
header_with_permalink_pattern = re.compile(r"^(#{1,6}) (.+?)(\s*\{\s*#.*\s*\})\s*$")
code_block3_pattern = re.compile(r"^\s*```")
code_block4_pattern = re.compile(r"^\s*````")


# Pattern to match markdown links: [text](url) → text
md_link_pattern = re.compile(r"\[([^\]]+)\]\([^)]+\)")


def strip_markdown_links(text: str) -> str:
    """Replace markdown links with just their visible text."""
    return md_link_pattern.sub(r"\1", text)


class VisibleTextExtractor(HTMLParser):
    """Extract visible text from a string with HTML tags."""

    def __init__(self):
        super().__init__()
        self.text_parts = []

    def handle_data(self, data):
        self.text_parts.append(data)

    def extract_visible_text(self, html: str) -> str:
        self.reset()
        self.text_parts = []
        self.feed(html)
        return "".join(self.text_parts).strip()


def slugify(text: str) -> str:
    return py_slugify(
        text,
        replacements=[
            ("`", ""),  # `dict`s -> dicts
            ("'s", "s"),  # it's -> its
            ("'t", "t"),  # don't -> dont
            ("**", ""),  # **FastAPI**s -> FastAPIs
        ],
    )


def get_en_config() -> dict[str, Any]:
    return yaml.unsafe_load(en_config_path.read_text(encoding="utf-8"))


def get_lang_paths() -> list[Path]:
    return sorted(docs_path.iterdir())


def lang_callback(lang: str | None) -> str | None:
    if lang is None:
        return None
    lang = lang.lower()
    return lang


def complete_existing_lang(incomplete: str):
    lang_path: Path
    for lang_path in get_lang_paths():
        if lang_path.is_dir() and lang_path.name.startswith(incomplete):
            yield lang_path.name


@app.callback()
def callback() -> None:
    # For MacOS with Cairo
    os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"


@app.command()
def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
    """
    Generate a new docs translation directory for the language LANG.
    """
    new_path: Path = Path("docs") / lang
    if new_path.exists():
        typer.echo(f"The language was already created: {lang}")
        raise typer.Abort()
    new_path.mkdir()
    new_llm_prompt_path: Path = new_path / "llm-prompt.md"
    new_llm_prompt_path.write_text("", encoding="utf-8")
    print(f"Successfully initialized: {new_path}")
    update_languages()


@app.command()
def build_lang(
    lang: str = typer.Argument(
        ..., callback=lang_callback, autocompletion=complete_existing_lang
    ),
) -> None:
    """
    Build the docs for a language.
    """
    build_zensical_lang_to_stage(lang)
    copy_zensical_stage_to_site(lang)
    typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)


def split_markdown_header(markdown: str) -> tuple[str, str]:
    prefix = ""
    if markdown.startswith("---\n"):
        front_matter_end = markdown.find("\n---\n", 4)
        if front_matter_end != -1:
            front_matter_end += len("\n---\n")
            prefix = markdown[:front_matter_end]
            markdown = markdown[front_matter_end:]
    if markdown.startswith("#"):
        header, separator, body = markdown.partition("\n\n")
        if separator:
            return f"{prefix}{header}", body
    if prefix:
        return prefix.rstrip("\n"), markdown
    return "", markdown


def add_markdown_notice(markdown: str, notice: str) -> str:
    header, body = split_markdown_header(markdown)
    if header:
        return f"{header}\n\n{notice}\n\n{body}"
    return f"{notice}\n\n{body}"


def is_non_translated_path(path: Path) -> bool:
    src_path = path.as_posix()
    return any(src_path.startswith(section) for section in non_translated_sections)


def get_en_url(path: Path) -> str:
    url_path = path.with_suffix("").as_posix()
    if url_path.endswith("/index"):
        url_path = url_path.removesuffix("index")
    elif url_path != "index":
        url_path = f"{url_path}/"
    else:
        url_path = ""
    return f"https://fastapi.tiangolo.com/{url_path}"


def get_zensical_theme_language(lang: str) -> str:
    if lang == "zh-hant":
        return "zh-Hant"
    return lang


def stage_zensical_docs(lang: str) -> Path:
    lang_docs_path = docs_path / lang / "docs"
    if not lang_docs_path.is_dir():
        typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
        raise typer.Abort()

    en_docs_source_path = en_docs_path / "docs"
    staged_docs_src_path = zensical_src_path / "docs_src"
    if not staged_docs_src_path.exists():
        shutil.copytree(Path("docs_src"), staged_docs_src_path, dirs_exist_ok=True)
    lang_stage_path = zensical_src_path / lang
    staged_docs_path = lang_stage_path / "content"
    shutil.rmtree(lang_stage_path, ignore_errors=True)
    shutil.copytree(en_docs_source_path, staged_docs_path)

    missing_translation = (docs_path / "missing-translation.md").read_text(
        encoding="utf-8"
    )
    translation_banner_path = lang_docs_path / "translation-banner.md"
    if not translation_banner_path.is_file():
        translation_banner_path = en_docs_source_path / "translation-banner.md"
    translation_banner = translation_banner_path.read_text(encoding="utf-8")

    if lang != "en":
        for staged_file in staged_docs_path.rglob("*.md"):
            relative_path = staged_file.relative_to(staged_docs_path)
            translated_file = lang_docs_path / relative_path
            if translated_file.is_file():
                markdown = translated_file.read_text(encoding="utf-8")
                if relative_path.name == "translation-banner.md":
                    staged_file.write_text(markdown, encoding="utf-8")
                    continue
                en_url = get_en_url(relative_path)
                banner = translation_banner.replace("ENGLISH_VERSION_URL", en_url)
                staged_file.write_text(
                    add_markdown_notice(markdown, banner), encoding="utf-8"
                )
            elif not is_non_translated_path(relative_path):
                markdown = staged_file.read_text(encoding="utf-8")
                staged_file.write_text(
                    add_markdown_notice(markdown, missing_translation),
                    encoding="utf-8",
                )

    shutil.copytree(en_docs_path / "data", lang_stage_path / "data")
    shutil.copytree(en_docs_path / "overrides", lang_stage_path / "overrides")

    config = get_updated_config_content()
    config["docs_dir"] = "content"
    config["site_dir"] = "site"
    if lang == "en":
        config["site_url"] = "https://fastapi.tiangolo.com/"
    else:
        config["site_url"] = f"https://fastapi.tiangolo.com/{lang}/"
    config.setdefault("theme", {})
    config["theme"]["language"] = get_zensical_theme_language(lang)
    if lang != "en":
        # The root English build owns shared static assets; translated builds should
        # reference those root paths instead of emitting language-local copies.
        if "logo" in config["theme"]:
            config["theme"]["logo"] = "/" + config["theme"]["logo"].lstrip("/")
        if "favicon" in config["theme"]:
            config["theme"]["favicon"] = "/" + config["theme"]["favicon"].lstrip("/")
        config["extra_css"] = ["/" + path.lstrip("/") for path in config["extra_css"]]
        config["extra_javascript"] = [
            "/" + path.lstrip("/") for path in config["extra_javascript"]
        ]
    config_path = lang_stage_path / mkdocs_name
    config_path.write_text(
        yaml.dump(config, sort_keys=False, width=200, allow_unicode=True),
        encoding="utf-8",
    )
    return config_path


def build_zensical_config(config_path: Path) -> None:
    subprocess.run(
        ["zensical", "build", "--config-file", config_path.name],
        check=True,
        cwd=config_path.parent,
    )


def build_zensical_lang_to_stage(lang: str) -> Path:
    typer.echo(f"Building Zensical docs for: {lang}")
    config_path = stage_zensical_docs(lang)
    config = yaml.unsafe_load(config_path.read_text(encoding="utf-8"))
    build_site_dist_path = config_path.parent / config["site_dir"]
    shutil.rmtree(build_site_dist_path, ignore_errors=True)
    build_zensical_config(config_path)
    return build_site_dist_path


def copy_zensical_stage_to_site(lang: str) -> None:
    build_site_dist_path = zensical_src_path / lang / "site"
    if lang == "en":
        dist_path = site_path
    else:
        dist_path = site_path / lang
        shutil.rmtree(dist_path, ignore_errors=True)
    shutil.copytree(build_site_dist_path, dist_path, dirs_exist_ok=True)


index_sponsors_template = """
### Keystone Sponsor

{% for sponsor in sponsors.keystone -%}
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
{% endfor %}
### Gold Sponsors

{% for sponsor in sponsors.gold -%}
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
{% endfor %}
### Silver Sponsors

{% for sponsor in sponsors.silver -%}
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
{% endfor %}

"""


def remove_header_permalinks(content: str):
    lines: list[str] = []
    for line in content.split("\n"):
        match = header_with_permalink_pattern.match(line)
        if match:
            hashes, title, *_ = match.groups()
            line = f"{hashes} {title}"
        lines.append(line)
    return "\n".join(lines)


def generate_readme_content() -> str:
    en_index = en_docs_path / "docs" / "index.md"
    content = en_index.read_text("utf-8")
    content = remove_header_permalinks(content)  # remove permalinks from headers
    match_pre = re.search(r"</style>\n\n", content)
    match_start = re.search(r"<!-- sponsors -->", content)
    match_end = re.search(r"<!-- /sponsors -->", content)
    sponsors_data_path = en_docs_path / "data" / "sponsors.yml"
    sponsors = yaml.safe_load(sponsors_data_path.read_text(encoding="utf-8"))
    if not (match_start and match_end):
        raise RuntimeError("Couldn't auto-generate sponsors section")
    if not match_pre:
        raise RuntimeError("Couldn't find pre section (<style>) in index.md")
    frontmatter_end = match_pre.end()
    pre_end = match_start.end()
    post_start = match_end.start()
    template = Template(index_sponsors_template)
    message = template.render(sponsors=sponsors)
    pre_content = content[frontmatter_end:pre_end]
    post_content = content[post_start:]
    new_content = pre_content + message + post_content
    # Remove content between <!-- only-mkdocs --> and <!-- /only-mkdocs -->
    new_content = re.sub(
        r"<!-- only-mkdocs -->.*?<!-- /only-mkdocs -->",
        "",
        new_content,
        flags=re.DOTALL,
    )
    return new_content


@app.command()
def generate_readme() -> None:
    """
    Generate README.md content from main index.md
    """
    readme_path = Path("README.md")
    old_content = readme_path.read_text("utf-8")
    new_content = generate_readme_content()
    if new_content != old_content:
        print("README.md outdated from the latest index.md")
        print("Updating README.md")
        readme_path.write_text(new_content, encoding="utf-8")
        raise typer.Exit(1)
    print("README.md is up to date ✅")


@app.command()
def build_all() -> None:
    """
    Build the full translated docs site into ./site/.
    """
    update_languages()
    shutil.rmtree(site_path, ignore_errors=True)
    shutil.rmtree(zensical_src_path, ignore_errors=True)
    shutil.copytree(Path("docs_src"), zensical_src_path / "docs_src")
    langs = [
        lang.name
        for lang in get_lang_paths()
        if (lang.is_dir() and lang.name in SUPPORTED_LANGS)
    ]
    process_pool_size = min(4, len(langs), os.cpu_count() or 1)
    typer.echo(f"Using process pool size: {process_pool_size}")
    with Pool(process_pool_size) as p:
        p.map(build_zensical_lang_to_stage, langs)
    if "en" in langs:
        copy_zensical_stage_to_site("en")
    for lang in langs:
        if lang != "en":
            copy_zensical_stage_to_site(lang)
    typer.secho("Successfully built all docs", color=typer.colors.GREEN)


@app.command()
def update_languages() -> None:
    """
    Update the docs config Languages section including all the available languages.
    """
    old_config = get_en_config()
    updated_config = get_updated_config_content()
    if old_config != updated_config:
        print("docs/en/mkdocs.yml outdated")
        print("Updating docs/en/mkdocs.yml")
        en_config_path.write_text(
            yaml.dump(updated_config, sort_keys=False, width=200, allow_unicode=True),
            encoding="utf-8",
        )
        raise typer.Exit(1)
    print("docs/en/mkdocs.yml is up to date ✅")


@app.command()
def serve() -> None:
    """
    A quick server to preview a built site with translations.

    For development, prefer the command live.

    This is here only to preview a site with translations already built.

    Make sure you run the build-all command first.
    """
    typer.echo("Warning: this is a very simple server.")
    typer.echo("For development, use the command live instead.")
    typer.echo("This is here only to preview a site with translations already built.")
    typer.echo("Make sure you run the build-all command first.")
    os.chdir("site")
    server_address = ("", 8008)
    server = HTTPServer(server_address, SimpleHTTPRequestHandler)
    typer.echo("Serving at: http://127.0.0.1:8008")
    server.serve_forever()


@app.command()
def live() -> None:
    """
    Serve the English docs with livereload from the source files.
    """
    subprocess.run(
        [
            "zensical",
            "serve",
            "--config-file",
            mkdocs_name,
            "--dev-addr",
            "127.0.0.1:8008",
        ],
        cwd=en_docs_path,
        check=True,
    )


def get_updated_config_content() -> dict[str, Any]:
    config = get_en_config()
    languages = [{"en": "/"}]
    new_alternate: list[dict[str, str]] = []
    # Language names sourced from https://quickref.me/iso-639-1
    # Contributors may wish to update or change these, e.g. to fix capitalization.
    language_names_path = Path(__file__).parent / "../docs/language_names.yml"
    local_language_names: dict[str, str] = yaml.safe_load(
        language_names_path.read_text(encoding="utf-8")
    )
    for lang_path in get_lang_paths():
        if lang_path.name in {"en", "em"} or not lang_path.is_dir():
            continue
        if lang_path.name not in SUPPORTED_LANGS:
            # Skip languages that are not yet ready
            continue
        code = lang_path.name
        languages.append({code: f"/{code}/"})
    for lang_dict in languages:
        code = list(lang_dict.keys())[0]
        url = lang_dict[code]
        if code not in local_language_names:
            print(
                f"Missing language name for: {code}, "
                "update it in docs/language_names.yml"
            )
            raise typer.Abort()
        use_name = f"{code} - {local_language_names[code]}"
        new_alternate.append({"link": url, "name": use_name})
    config["extra"]["alternate"] = new_alternate
    return config


@app.command()
def ensure_non_translated() -> None:
    """
    Ensure there are no files in the non translatable pages.
    """
    print("Ensuring no non translated pages")
    lang_paths = get_lang_paths()
    error_paths = []
    for lang in lang_paths:
        if lang.name == "en":
            continue
        for non_translatable in non_translated_sections:
            non_translatable_path = lang / "docs" / non_translatable
            if non_translatable_path.exists():
                error_paths.append(non_translatable_path)
    if error_paths:
        print("Non-translated pages found, removing them:")
        for error_path in error_paths:
            print(error_path)
            if error_path.is_file():
                error_path.unlink()
            else:
                shutil.rmtree(error_path)
        raise typer.Exit(1)
    print("No non-translated pages found ✅")


@app.command()
def langs_json():
    langs = []
    for lang_path in get_lang_paths():
        if lang_path.is_dir() and lang_path.name in SUPPORTED_LANGS:
            langs.append(lang_path.name)
    print(json.dumps(langs))


@app.command()
def generate_docs_src_versions_for_file(file_path: Path) -> None:
    target_versions = ["py39", "py310"]
    full_path_str = str(file_path)
    for target_version in target_versions:
        if f"_{target_version}" in full_path_str:
            logging.info(
                f"Skipping {file_path}, already a version file for {target_version}"
            )
            return
    base_content = file_path.read_text(encoding="utf-8")
    previous_content = {base_content}
    for target_version in target_versions:
        version_result = subprocess.run(
            [
                find_ruff_bin(),
                "check",
                "--target-version",
                target_version,
                "--fix",
                "--unsafe-fixes",
                "-",
            ],
            input=base_content.encode("utf-8"),
            capture_output=True,
        )
        content_target = version_result.stdout.decode("utf-8")
        format_result = subprocess.run(
            [find_ruff_bin(), "format", "-"],
            input=content_target.encode("utf-8"),
            capture_output=True,
        )
        content_format = format_result.stdout.decode("utf-8")
        if content_format in previous_content:
            continue
        previous_content.add(content_format)
        # Determine where the version label should go: in the parent directory
        # name or in the file name, matching the source structure.
        label_in_parent = False
        for v in target_versions:
            if f"_{v}" in file_path.parent.name:
                label_in_parent = True
                break
        if label_in_parent:
            parent_name = file_path.parent.name
            for v in target_versions:
                parent_name = parent_name.replace(f"_{v}", "")
            new_parent = file_path.parent.parent / f"{parent_name}_{target_version}"
            new_parent.mkdir(parents=True, exist_ok=True)
            version_file = new_parent / file_path.name
        else:
            base_name = file_path.stem
            for v in target_versions:
                if base_name.endswith(f"_{v}"):
                    base_name = base_name[: -len(f"_{v}")]
                    break
            version_file = file_path.with_name(f"{base_name}_{target_version}.py")
        logging.info(f"Writing to {version_file}")
        version_file.write_text(content_format, encoding="utf-8")


@app.command()
def generate_docs_src_versions() -> None:
    """
    Generate Python version-specific files for all .py files in docs_src.
    """
    docs_src_path = Path("docs_src")
    for py_file in sorted(docs_src_path.rglob("*.py")):
        generate_docs_src_versions_for_file(py_file)


@app.command()
def copy_py39_to_py310() -> None:
    """
    For each docs_src file/directory with a _py39 label that has no _py310
    counterpart, copy it with the _py310 label.
    """
    docs_src_path = Path("docs_src")
    # Handle directory-level labels (e.g. app_b_an_py39/)
    for dir_path in sorted(docs_src_path.rglob("*_py39")):
        if not dir_path.is_dir():
            continue
        py310_dir = dir_path.parent / dir_path.name.replace("_py39", "_py310")
        if py310_dir.exists():
            continue
        logging.info(f"Copying directory {dir_path} -> {py310_dir}")
        shutil.copytree(dir_path, py310_dir)
    # Handle file-level labels (e.g. tutorial001_py39.py)
    for file_path in sorted(docs_src_path.rglob("*_py39.py")):
        if not file_path.is_file():
            continue
        # Skip files inside _py39 directories (already handled above)
        if "_py39" in file_path.parent.name:
            continue
        py310_file = file_path.with_name(
            file_path.name.replace("_py39.py", "_py310.py")
        )
        if py310_file.exists():
            continue
        logging.info(f"Copying file {file_path} -> {py310_file}")
        shutil.copy2(file_path, py310_file)


@app.command()
def update_docs_includes_py39_to_py310() -> None:
    """
    Update .md files in docs/en/ to replace _py39 includes with _py310 versions.

    For each include line referencing a _py39 file or directory in docs_src, replace
    the _py39 label with _py310.
    """
    include_pattern = re.compile(r"\{[^}]*docs_src/[^}]*_py39[^}]*\.py[^}]*\}")
    count = 0
    for md_file in sorted(en_docs_path.rglob("*.md")):
        content = md_file.read_text(encoding="utf-8")
        if "_py39" not in content:
            continue
        new_content = include_pattern.sub(
            lambda m: m.group(0).replace("_py39", "_py310"), content
        )
        if new_content != content:
            md_file.write_text(new_content, encoding="utf-8")
            count += 1
            logging.info(f"Updated includes in {md_file}")
    print(f"Updated {count} file(s) ✅")


@app.command()
def remove_unused_docs_src() -> None:
    """
    Delete .py files in docs_src that are not included in any .md file under docs/.
    """
    docs_src_path = Path("docs_src")
    # Collect all docs .md content referencing docs_src
    all_docs_content = ""
    for md_file in docs_path.rglob("*.md"):
        all_docs_content += md_file.read_text(encoding="utf-8")
    # Build a set of directory-based package roots (e.g. docs_src/bigger_applications/app_py39)
    # where at least one file is referenced in docs. All files in these directories
    # should be kept since they may be internally imported by the referenced files.
    used_package_dirs: set[Path] = set()
    for py_file in docs_src_path.rglob("*.py"):
        if py_file.name == "__init__.py":
            continue
        rel_path = str(py_file)
        if rel_path in all_docs_content:
            # Walk up from the file's parent to find the package root
            # (a subdirectory under docs_src/<topic>/)
            parts = py_file.relative_to(docs_src_path).parts
            if len(parts) > 2:
                # File is inside a sub-package like docs_src/topic/app_xxx/...
                package_root = docs_src_path / parts[0] / parts[1]
                used_package_dirs.add(package_root)
    removed = 0
    for py_file in sorted(docs_src_path.rglob("*.py")):
        if py_file.name == "__init__.py":
            continue
        # Build the relative path as it appears in includes (e.g. docs_src/first_steps/tutorial001.py)
        rel_path = str(py_file)
        if rel_path in all_docs_content:
            continue
        # If this file is inside a directory-based package where any sibling is
        # referenced, keep it (it's likely imported internally).
        parts = py_file.relative_to(docs_src_path).parts
        if len(parts) > 2:
            package_root = docs_src_path / parts[0] / parts[1]
            if package_root in used_package_dirs:
                continue
        # Check if the _an counterpart (or non-_an counterpart) is referenced.
        # If either variant is included, keep both.
        # Handle both file-level _an (tutorial001_an.py) and directory-level _an
        # (app_an/main.py)
        counterpart_found = False
        full_path_str = str(py_file)
        if "_an" in py_file.stem:
            # This is an _an file, check if the non-_an version is referenced
            counterpart = full_path_str.replace(
                f"/{py_file.stem}", f"/{py_file.stem.replace('_an', '', 1)}"
            )
            if counterpart in all_docs_content:
                counterpart_found = True
        else:
            # This is a non-_an file, check if there's an _an version referenced
            # Insert _an before any version suffix or at the end of the stem
            stem = py_file.stem
            for suffix in ("_py39", "_py310"):
                if suffix in stem:
                    an_stem = stem.replace(suffix, f"_an{suffix}", 1)
                    break
            else:
                an_stem = f"{stem}_an"
            counterpart = full_path_str.replace(f"/{stem}.", f"/{an_stem}.")
            if counterpart in all_docs_content:
                counterpart_found = True
        # Also check directory-level _an counterparts
        if not counterpart_found:
            parent_name = py_file.parent.name
            if "_an" in parent_name:
                counterpart_parent = parent_name.replace("_an", "", 1)
                counterpart_dir = str(py_file).replace(
                    f"/{parent_name}/", f"/{counterpart_parent}/"
                )
                if counterpart_dir in all_docs_content:
                    counterpart_found = True
            else:
                # Try inserting _an into parent directory name
                for suffix in ("_py39", "_py310"):
                    if suffix in parent_name:
                        an_parent = parent_name.replace(suffix, f"_an{suffix}", 1)
                        break
                else:
                    an_parent = f"{parent_name}_an"
                counterpart_dir = str(py_file).replace(
                    f"/{parent_name}/", f"/{an_parent}/"
                )
                if counterpart_dir in all_docs_content:
                    counterpart_found = True
        if counterpart_found:
            continue
        logging.info(f"Removing unused file: {py_file}")
        py_file.unlink()
        removed += 1
    # Clean up directories that are empty or only contain __init__.py / __pycache__
    for dir_path in sorted(docs_src_path.rglob("*"), reverse=True):
        if not dir_path.is_dir():
            continue
        remaining = [
            f
            for f in dir_path.iterdir()
            if f.name != "__pycache__" and f.name != "__init__.py"
        ]
        if not remaining:
            logging.info(f"Removing empty/init-only directory: {dir_path}")
            shutil.rmtree(dir_path)
    print(f"Removed {removed} unused file(s) ✅")


@app.command()
def add_permalinks_page(path: Path, update_existing: bool = False):
    """
    Add or update header permalinks in specific page of En docs.
    """

    if not path.is_relative_to(en_docs_path / "docs"):
        raise RuntimeError(f"Path must be inside {en_docs_path}")
    rel_path = path.relative_to(en_docs_path / "docs")

    # Skip excluded sections
    if str(rel_path).startswith(non_translated_sections):
        return

    visible_text_extractor = VisibleTextExtractor()
    updated_lines = []
    in_code_block3 = False
    in_code_block4 = False
    permalinks = set()

    with path.open("r", encoding="utf-8") as f:
        lines = f.readlines()

    for line in lines:
        # Handle codeblocks start and end
        if not (in_code_block3 or in_code_block4):
            if code_block4_pattern.match(line):
                in_code_block4 = True
            elif code_block3_pattern.match(line):
                in_code_block3 = True
        else:
            if in_code_block4 and code_block4_pattern.match(line):
                in_code_block4 = False
            elif in_code_block3 and code_block3_pattern.match(line):
                in_code_block3 = False

        # Process Headers only outside codeblocks
        if not (in_code_block3 or in_code_block4):
            match = header_pattern.match(line)
            if match:
                hashes, title, _permalink = match.groups()
                if (not _permalink) or update_existing:
                    slug = slugify(
                        visible_text_extractor.extract_visible_text(
                            strip_markdown_links(title)
                        )
                    )
                    if slug in permalinks:
                        # If the slug is already used, append a number to make it unique
                        count = 1
                        original_slug = slug
                        while slug in permalinks:
                            slug = f"{original_slug}_{count}"
                            count += 1
                    permalinks.add(slug)

                    line = f"{hashes} {title} {{ #{slug} }}\n"

        updated_lines.append(line)

    with path.open("w", encoding="utf-8") as f:
        f.writelines(updated_lines)


@app.command()
def add_permalinks_pages(pages: list[Path], update_existing: bool = False) -> None:
    """
    Add or update header permalinks in specific pages of En docs.
    """
    for md_file in pages:
        add_permalinks_page(md_file, update_existing=update_existing)


@app.command()
def add_permalinks(update_existing: bool = False) -> None:
    """
    Add or update header permalinks in all pages of En docs.
    """
    for md_file in en_docs_path.rglob("*.md"):
        add_permalinks_page(md_file, update_existing=update_existing)


if __name__ == "__main__":
    app()