From 1ffb0d87516697e746c92bca1bcbcb5ec1b44faa Mon Sep 17 00:00:00 2001 From: Koudai Aono Date: Fri, 19 Dec 2025 16:49:24 +0000 Subject: [PATCH] docs: Ensure deterministic order in generated documentation and update references --- docs/cli-reference/model-customization.md | 2 +- docs/cli-reference/openapi-only-options.md | 2 +- scripts/build_cli_docs.py | 12 +++++++++--- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/cli-reference/model-customization.md b/docs/cli-reference/model-customization.md index 6b9fcbf30..4028de379 100644 --- a/docs/cli-reference/model-customization.md +++ b/docs/cli-reference/model-customization.md @@ -4631,7 +4631,7 @@ The `--target-python-version` flag controls Python version-specific syntax: This affects import statements and type annotation syntax in generated code. -**See also:** [Output Model Types](../what_is_the_difference_between_v1_and_v2.md), [CI/CD Integration](../ci-cd.md), [Python Version Compatibility](../python-version-compatibility.md) +**See also:** [CI/CD Integration](../ci-cd.md), [Python Version Compatibility](../python-version-compatibility.md), [Output Model Types](../what_is_the_difference_between_v1_and_v2.md) !!! tip "Usage" diff --git a/docs/cli-reference/openapi-only-options.md b/docs/cli-reference/openapi-only-options.md index feba111f6..de3654ab6 100644 --- a/docs/cli-reference/openapi-only-options.md +++ b/docs/cli-reference/openapi-only-options.md @@ -1037,7 +1037,7 @@ The `--validation` flag configures the code generation behavior. **Deprecated:** Use --field-constraints instead -**See also:** [OpenAPI-Specific Options](../openapi-options.md), [Field Constraints](../field-constraints.md) +**See also:** [Field Constraints](../field-constraints.md), [OpenAPI-Specific Options](../openapi-options.md) !!! tip "Usage" diff --git a/scripts/build_cli_docs.py b/scripts/build_cli_docs.py index dfc00a18c..986c70961 100644 --- a/scripts/build_cli_docs.py +++ b/scripts/build_cli_docs.py @@ -192,7 +192,8 @@ def scan_docs_for_cli_option_tags() -> dict[str, list[tuple[str, str]]]: option_to_pages: dict[str, list[tuple[str, str]]] = defaultdict(list) # Scan all markdown files in docs/ (excluding cli-reference/) - for md_file in DOCS_ROOT.glob("**/*.md"): + # Sort to ensure consistent ordering across different environments + for md_file in sorted(DOCS_ROOT.glob("**/*.md")): # Skip cli-reference directory (auto-generated) try: md_file.relative_to(DOCS_OUTPUT) @@ -226,7 +227,8 @@ def scan_docs_for_cli_option_tags() -> dict[str, list[tuple[str, str]]]: canonical = get_canonical_option(option) option_to_pages[canonical].append((page_path, page_title)) - return dict(option_to_pages) + # Sort the page lists for each option to ensure consistent ordering + return {option: sorted(pages) for option, pages in sorted(option_to_pages.items())} def slugify(text: str) -> str: @@ -893,7 +895,11 @@ def write_or_check(output_path: Path, content: str, label: str) -> bool: generated += 1 return True - for category, options in categories.items(): + # Iterate in OptionCategory enum order for consistent output + for category in OptionCategory: + if category not in categories: + continue + options = categories[category] if not options: continue try: