From 836587ffed35dd99e2704bf3948093bb37d4f383 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 23 Sep 2025 17:22:14 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20format?= =?UTF-8?q?=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/docs.py | 84 ++++++++++++++++++++++++------------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/scripts/docs.py b/scripts/docs.py index eab245620..15ae621b6 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -74,7 +74,7 @@ header_with_permalink_pattern = re.compile(r"^(#{1,6}) (.+?)(\s*\{\s*#.*\s*\})\s def is_mkdocs_insiders() -> bool: """ Check if mkdocs-material insiders version is installed. - + Returns: bool: True if insiders version is detected, False otherwise """ @@ -85,7 +85,7 @@ def is_mkdocs_insiders() -> bool: def get_en_config() -> Dict[str, Any]: """ Load and parse the English documentation configuration file. - + Returns: Dict[str, Any]: Parsed YAML content from mkdocs.yml """ @@ -95,7 +95,7 @@ def get_en_config() -> Dict[str, Any]: def get_lang_paths() -> List[Path]: """ Get all language directory paths from the docs directory. - + Returns: List[Path]: Sorted list of Path objects for each language directory """ @@ -105,10 +105,10 @@ def get_lang_paths() -> List[Path]: def lang_callback(lang: Optional[str]) -> Union[str, None]: """ Typer callback function to normalize language input. - + Args: lang: Language code to normalize - + Returns: Normalized lowercase language code or None if input is None """ @@ -121,10 +121,10 @@ def lang_callback(lang: Optional[str]) -> Union[str, None]: def complete_existing_lang(incomplete: str): """ Autocomplete function for existing languages. - + Args: incomplete: Partial language name to complete - + Yields: str: Matching language directory names """ @@ -138,7 +138,7 @@ def complete_existing_lang(incomplete: str): def callback() -> None: """ Global callback function executed before any command. - + Sets up environment variables for mkdocs-insiders and MacOS Cairo support. """ if is_mkdocs_insiders(): @@ -151,13 +151,13 @@ def callback() -> None: def new_lang(lang: str = typer.Argument(..., callback=lang_callback)): """ Generate a new docs translation directory for the specified language. - + Creates the necessary directory structure, configuration file, and initial content for a new language translation. - + Args: lang: Language code for the new translation (e.g., 'es', 'fr') - + Raises: typer.Abort: If the language directory already exists """ @@ -187,13 +187,13 @@ def build_lang( ) -> None: """ Build the documentation for a specific language. - + Uses mkdocs to build the documentation site for the specified language and copies the output to the appropriate location. - + Args: lang: Language code to build (e.g., 'en', 'es') - + Raises: typer.Abort: If the language directory doesn't exist """ @@ -242,10 +242,10 @@ index_sponsors_template = """ def remove_header_permalinks(content: str) -> str: """ Remove permalinks from markdown headers. - + Args: content: Markdown content with header permalinks - + Returns: str: Markdown content with permalinks removed from headers """ @@ -262,13 +262,13 @@ def remove_header_permalinks(content: str) -> str: def generate_readme_content() -> str: """ Generate README.md content from the main English index.md file. - + Processes the index.md file to remove mkdocs-specific elements and generates appropriate content for GitHub README. - + Returns: str: Generated README content - + Raises: RuntimeError: If required sections are not found in the source content """ @@ -306,7 +306,7 @@ def generate_readme_content() -> str: def generate_readme() -> None: """ Generate README.md file from the main English documentation index.md. - + This command processes the main documentation index file to create a GitHub-appropriate README with sponsors information and without mkdocs-specific elements. @@ -321,10 +321,10 @@ def generate_readme() -> None: def verify_readme() -> None: """ Verify that README.md is up-to-date with the main documentation index. - + Compares the current README content with what would be generated from the main index.md file and reports any discrepancies. - + Raises: typer.Abort: If README.md is outdated """ @@ -344,13 +344,13 @@ def verify_readme() -> None: def build_all() -> None: """ Build documentation for all available languages. - + This command: 1. Updates language configurations 2. Cleans the output directory 3. Builds documentation for all languages in parallel 4. Places the final output in the site/ directory - + Uses multiprocessing for efficient parallel builds across all CPU cores. """ update_languages() @@ -367,7 +367,7 @@ def build_all() -> None: def update_languages() -> None: """ Update the mkdocs.yml file with all available languages. - + This command regenerates the language configuration section in the main mkdocs.yml file to include all currently available translations. """ @@ -378,10 +378,10 @@ def update_languages() -> None: def serve() -> None: """ Start a simple HTTP server to preview the built documentation site. - + This is a basic server for previewing the complete built site with all translations. For development, use the 'live' command instead. - + Note: Requires running 'build-all' first to generate the site. """ typer.echo("Warning: this is a very simple server.") @@ -404,10 +404,10 @@ def live( ) -> None: """ Serve documentation with live reload for a specific language. - + This command starts a mkdocs development server with livereload functionality for real-time preview during documentation development. - + Args: lang: Language to serve (defaults to 'en' if not specified) dirty: Use dirty build mode for faster rebuilds @@ -428,13 +428,13 @@ def live( def get_updated_config_content() -> Dict[str, Any]: """ Generate updated mkdocs configuration with all available languages. - + Reads the language names from language_names.yml and generates the complete alternate language configuration for the mkdocs.yml file. - + Returns: Dict[str, Any]: Updated mkdocs configuration with all languages - + Raises: typer.Abort: If a language code is missing from language_names.yml """ @@ -471,7 +471,7 @@ def get_updated_config_content() -> Dict[str, Any]: def update_config() -> None: """ Update the main English mkdocs.yml file with current language configuration. - + Writes the updated configuration generated by get_updated_config_content() back to the mkdocs.yml file. """ @@ -486,10 +486,10 @@ def update_config() -> None: def verify_config() -> None: """ Verify that mkdocs.yml is up-to-date with language names. - + Checks if the current mkdocs.yml configuration matches what would be generated from the current language_names.yml file. - + Raises: typer.Abort: If mkdocs.yml is outdated """ @@ -511,10 +511,10 @@ def verify_config() -> None: def verify_non_translated() -> None: """ Verify that non-translatable sections don't exist in translation directories. - + Checks all language directories (except English) to ensure they don't contain files or directories that are marked as non-translatable. - + Raises: typer.Abort: If non-translatable content is found in translation directories """ @@ -540,12 +540,12 @@ def verify_non_translated() -> None: def verify_docs() -> None: """ Run all documentation verification checks. - + This command runs a comprehensive verification including: - README.md validation - mkdocs.yml configuration validation - Non-translated content validation - + This is useful as a pre-commit or CI check to ensure documentation integrity. """ verify_readme() @@ -557,7 +557,7 @@ def verify_docs() -> None: def langs_json() -> None: """ Output all available language codes as JSON. - + Prints a JSON array containing all available language codes found in the docs directory. Useful for scripting and automation. """ @@ -572,10 +572,10 @@ def langs_json() -> None: def generate_docs_src_versions_for_file(file_path: Path) -> None: """ Generate Python source file versions for different Python versions. - + Uses ruff to generate version-specific Python files for documentation examples, targeting different Python versions. - + Args: file_path: Path to the source Python file to generate versions for """