docs: Ensure deterministic order in generated documentation and update references (#2698)

Author: koxudaxi

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"
 

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"
 

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: