[tools]: Add sync script and CI check for Miles server args sync

[Ratish1]

Summary

This is part 2 of the PR that implements the sync script requested in #578 and adds a l CPU CI check.

Added

• tools/sync_param_docs.py
• .github/workflows/param-docs-sync-check.yml

Script behavior

tools/sync_param_docs.py supports:

• --check: validation-only, fails when docs and args are out of sync
• --write: syncs managed docs descriptions from code

Scope rules

• Managed source-of-truth: explicit Miles-native flags defined in miles/utils/arguments.py via:
  • parser.add_argument("--...")
  • reset_arg(parser, "--...", ...)
• Intentionally undocumented flags are excluded by explicit allowlist/exclusion logic.
• We do not mirror all python train.py --help output.
• We do not auto-edit arguments.py from docs.

Bi-directional consistency checks

--check validates both directions:

• args -> docs: every managed code flag is documented and up to date
• docs -> args: every managed docs flag exists in managed code scope

CI

Added a CPU-only workflow:

• .github/workflows/param-docs-sync-check.yml
• Runs: python tools/sync_param_docs.py --check
• Triggered on PR/push when:
  • docs/en/advanced/miles_server_args.md changes
  • miles/utils/arguments.py changes

Verification

Before manual sync (expected fail)

Using pre-sync snapshots:

• --check fails with stale descriptions / missing help entries.

After manual sync (expected pass)

• --check passes with zero stale/missing/duplicate issues.

Write mode check locally

• --write updated 1 row

python tools/sync_param_docs.py --check
python tools/sync_param_docs.py --write

[gemini-code-assist]

Summary of Changes

Hello @Ratish1, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the maintainability and accuracy of Miles server argument documentation by introducing an automated synchronization and validation system. It ensures that the documentation consistently reflects the current state of argument definitions in the codebase, thereby reducing manual effort and preventing documentation drift. The integration into the CI pipeline provides continuous verification, making it easier for developers to keep documentation up-to-date.

Highlights

• New Synchronization Script: Added a Python script (tools/sync_param_docs.py) designed to synchronize and validate Miles server argument documentation against their definitions in miles/utils/arguments.py.
• Script Functionality: The script supports two primary modes: --check for validation-only, which identifies discrepancies, and --write for automatically updating managed documentation descriptions from code help strings.
• Defined Scope and Exclusions: Established clear rules for which arguments are managed (explicitly defined in arguments.py) and included an explicit allowlist/exclusion logic for intentionally undocumented flags.
• Bi-directional Consistency: Implemented comprehensive checks to ensure both directions of consistency: every managed code flag is documented and up-to-date, and every managed documented flag exists in the code scope.
• CI Integration: Introduced a new GitHub Actions CI workflow (.github/workflows/param-docs-sync-check.yml) that automatically runs the --check script on pull requests and pushes when relevant documentation or argument definition files are modified.

Changelog

• .github/workflows/param-docs-sync-check.yml
  • Established a new GitHub Actions workflow to enforce documentation consistency for Miles server arguments.
  • Configured the workflow to trigger on pull requests and pushes when docs/en/advanced/miles_server_args.md or miles/utils/arguments.py are modified.
  • Set up the workflow to execute the sync_param_docs.py script in --check mode, failing the CI if inconsistencies are detected.
• tools/sync_param_docs.py
  • Introduced a new Python script to automate the synchronization and validation of Miles server argument documentation with their code definitions.
  • Implemented functionality to parse argument definitions from miles/utils/arguments.py and markdown documentation from miles_server_args.md.
  • Provided --check mode for validation and --write mode for automatic updates of documentation descriptions, including handling of escaped characters in markdown.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/param-docs-sync-check.yml

Activity

• The author performed verification steps, including testing the --check mode with pre-sync snapshots (expected to fail) and after manual synchronization (expected to pass).
• The --write mode was also verified locally, confirming it updated one row as expected.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable script for synchronizing and validating the command-line argument documentation, which is a great step towards ensuring documentation accuracy. The script is well-designed, using ast parsing for reliability and providing both a validation (--check) and an update (--write) mode. My review focuses on a couple of areas for improvement: enhancing robustness by specifying exception types and increasing conciseness by leveraging regular expressions for string manipulation. Overall, this is a solid contribution that improves project maintainability.

[gemini-code-assist]

The manual iteration to escape unescaped pipe characters is correct, but it can be significantly simplified by using a regular expression with a negative lookbehind. This makes the code more concise, idiomatic, and often easier to understand for developers familiar with regex.

Suggested change

	def _escape_unescaped_pipes(text: str) -> str:
	out: list[str] = []
	escaped = False
	for ch in text:
	if escaped:
	out.append(ch)
	escaped = False
	continue
	if ch == "\\":
	out.append(ch)
	escaped = True
	continue
	if ch == "|":
	out.append("\\|")
	else:
	out.append(ch)
	return "".join(out)
	def _escape_unescaped_pipes(text: str) -> str:
	# Use a negative lookbehind to find '|' not preceded by '\'.
	return re.sub(r"(?<!\\)\|", r"\\|", text)