From f795fe352d55e0924f5d7bc099f36e47d715c56f Mon Sep 17 00:00:00 2001 From: Martin Hickey Date: Thu, 8 Oct 2026 08:37:22 +0100 Subject: [PATCH] [Test] Add a docs drift check for server_arguments.mdx (#38520) Signed-off-by: Martin Hickey Co-authored-by: Cheng Wan <54331508+ch-wan@users.noreply.github.com> Co-authored-by: Cheng Wan --- .github/workflows/_pr-test-check-changes.yml | 11 ++ .github/workflows/_pr-test-stage-cpu.yml | 4 +- docs/.mintignore | 3 + .../advanced_features/server_arguments.mdx | 55 +------ .../server_arguments_undocumented.txt | 95 ++++++++++++ .../test_server_args_docs_coverage.py | 145 ++++++++++++++++++ 6 files changed, 264 insertions(+), 49 deletions(-) create mode 100644 docs/docs/advanced_features/server_arguments_undocumented.txt create mode 100644 test/registered/unit/server_args/test_server_args_docs_coverage.py diff --git a/.github/workflows/_pr-test-check-changes.yml b/.github/workflows/_pr-test-check-changes.yml index 870c00118e..b89eb8e167 100644 --- a/.github/workflows/_pr-test-check-changes.yml +++ b/.github/workflows/_pr-test-check-changes.yml @@ -29,6 +29,8 @@ on: value: ${{ jobs.run.outputs.multimodal_gen }} renderer: value: ${{ jobs.run.outputs.renderer }} + server_args_docs: + value: ${{ jobs.run.outputs.server_args_docs }} rust_workspace: value: ${{ jobs.run.outputs.rust_workspace }} partitions: @@ -53,6 +55,7 @@ jobs: jit_kernel: ${{ steps.filter.outputs.jit_kernel || steps.run-mode.outputs.run_all_tests }} multimodal_gen: ${{ steps.filter.outputs.multimodal_gen || steps.run-mode.outputs.run_all_tests }} renderer: ${{ steps.filter.outputs.renderer || steps.run-mode.outputs.run_all_tests }} + server_args_docs: ${{ steps.filter.outputs.server_args_docs || steps.run-mode.outputs.run_all_tests }} rust_workspace: ${{ steps.filter.outputs.rust_workspace || steps.run-mode.outputs.run_all_tests }} partitions: ${{ steps.partitions.outputs.partitions }} partition_model_sha: ${{ steps.partition-model-sha.outputs.sha }} @@ -115,6 +118,13 @@ jobs: renderer: - "rust/sglang-renderer/**" - "rust/sglang-processor/**" + server_args_docs: + # test_server_args_docs_coverage.py diffs this doc and its allowlist + # against the CLI, so a docs only edit can break that test. Kept out + # of main_package which also gates every GPU stage. Only the CPU + # stage reads this. + - "docs/docs/advanced_features/server_arguments.mdx" + - "docs/docs/advanced_features/server_arguments_undocumented.txt" simulator: - ".github/workflows/pr-test-extra.yml" - ".github/workflows/_pr-test-simulator-cpu.yml" @@ -271,6 +281,7 @@ jobs: echo "| jit_kernel | ${{ steps.filter.outputs.jit_kernel || steps.run-mode.outputs.run_all_tests }} |" echo "| multimodal_gen | ${{ steps.filter.outputs.multimodal_gen || steps.run-mode.outputs.run_all_tests }} |" echo "| rust_workspace | ${{ steps.filter.outputs.rust_workspace || steps.run-mode.outputs.run_all_tests }} |" + echo "| server_args_docs | ${{ steps.filter.outputs.server_args_docs || steps.run-mode.outputs.run_all_tests }} |" echo "| b200_runner | ${{ steps.set-runner.outputs.b200_runner }} |" echo "| enable_retry | ${{ steps.set-retry.outputs.enable_retry }} |" echo "| continue_on_error | ${{ steps.set-continue-on-error.outputs.continue_on_error }} |" diff --git a/.github/workflows/_pr-test-stage-cpu.yml b/.github/workflows/_pr-test-stage-cpu.yml index 9206c8761d..d98c0feff2 100644 --- a/.github/workflows/_pr-test-stage-cpu.yml +++ b/.github/workflows/_pr-test-stage-cpu.yml @@ -13,7 +13,7 @@ on: type: string required: true check_changes: - description: 'toJson(needs.check-changes.outputs). Read via fromJson(...).main_package / renderer / rust_workspace / continue_on_error / partition_model_sha.' + description: 'toJson(needs.check-changes.outputs). Read via fromJson(...).main_package / renderer / server_args_docs / rust_workspace / continue_on_error / partition_model_sha.' type: string required: true caller_inputs: @@ -49,7 +49,7 @@ jobs: # emits a skipped entry for wait-for-jobs to match. The schedule / # parallel-dispatch / !failure() half stays on the caller, where the # `needs` context it guards actually lives. - if: fromJson(inputs.check_changes).main_package == 'true' || fromJson(inputs.check_changes).renderer == 'true' + if: fromJson(inputs.check_changes).main_package == 'true' || fromJson(inputs.check_changes).renderer == 'true' || fromJson(inputs.check_changes).server_args_docs == 'true' runs-on: ubuntu-latest timeout-minutes: 240 env: diff --git a/docs/.mintignore b/docs/.mintignore index 9922f06dc8..98923e24fe 100644 --- a/docs/.mintignore +++ b/docs/.mintignore @@ -5,3 +5,6 @@ # Draft content drafts/ *.draft.mdx + +# Data read by test_server_args_docs_coverage.py, not a page +advanced_features/server_arguments_undocumented.txt diff --git a/docs/docs/advanced_features/server_arguments.mdx b/docs/docs/advanced_features/server_arguments.mdx index cb3fea10a5..9a065c0c29 100644 --- a/docs/docs/advanced_features/server_arguments.mdx +++ b/docs/docs/advanced_features/server_arguments.mdx @@ -780,12 +780,6 @@ Please consult the documentation below and [server_args.py](https://github.com/s `False` bool flag (set to enable) - - `--custom-sigquit-handler` - Register a custom sigquit handler so you can do additional cleanup after the server is shutdown. This is only available for Engine, not for CLI. - `None` - Type: str - `--batch-notify-size` Number of streaming notifications to batch before yielding to the event loop. Reduces asyncio wakeup overhead under high concurrency. @@ -1611,6 +1605,12 @@ Combining `--enable-response-store` with `--disaggregation-mode=prefill` or `dec The accept probability of a draft token is raised from its target probability p to min(1, p / threshold_acc). `1.0` Type: float + + + `--speculative-use-block-verification` + Use block verification for EAGLE/EAGLE3/NEXTN on CUDA or ROCm (requires topk=1). + `False` + Type: bool `--speculative-token-map` @@ -2968,12 +2968,6 @@ This option does not disable required attention or MoE collectives, including ex The input filename for dumping tensors `None` Type: str - - - `--debug-tensor-dump-inject` - Inject the outputs from jax as the input of every layer. - `False` - Type: str @@ -3050,8 +3044,8 @@ This option does not disable required attention or MoE collectives, including ex bool flag (set to enable) - `--optimistic-prefill-retries` - Number of optimistic prefill retries that will skip the bootstrap wait. + `--optimistic-prefill-attempts` + Number of optimistic prefill forward passes that skip the bootstrap wait. `0` Type: int @@ -3434,36 +3428,3 @@ This option does not disable required attention or MoE collectives, including ex - -## Deprecated arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ArgumentDescriptionDefaultsOptions
`--hybrid-kvcache-ratio`Mix ratio in [0,1] between uniform and hybrid kv buffers (0.0 = pure uniform: swa_size / full_size = 1)(1.0 = pure hybrid: swa_size / full_size = local_attention_size / context_length)`None`Optional[float]
diff --git a/docs/docs/advanced_features/server_arguments_undocumented.txt b/docs/docs/advanced_features/server_arguments_undocumented.txt new file mode 100644 index 0000000000..c56089778c --- /dev/null +++ b/docs/docs/advanced_features/server_arguments_undocumented.txt @@ -0,0 +1,95 @@ +# Live ServerArgs flags with no row in server_arguments.mdx. One flag per line. +# test/registered/unit/server_args/test_server_args_docs_coverage.py reads this +# list. It may only shrink: when you add a row for a flag, delete it here. +--c128-page-size +--constrained-json-max-whitespace-cnt +--cuda-graph-prefill-max-context +--decoupled-spec-bind-endpoint +--decoupled-spec-connect-endpoints +--decoupled-spec-rank +--decoupled-spec-role +--deepep-v2-mode +--disable-aiter-allreduce-fusion-in-decode +--disable-aiter-allreduce-fusion-in-prefill +--disaggregation-decode-extra-slots +--disaggregation-decode-host-receive-threshold +--disaggregation-decode-retraction-backup +--disaggregation-enable-kv-checksum +--dsa-paged-mqa-logits-backend +--dsv4-attn-backend +--dsv4-prefill-backend +--dwdp-size +--elastic-ep-initial-size +--elastic-ep-join-mode +--elastic-ep-join-rank-offset +--elastic-ep-scale-timeout +--enable-cp-decode-attn-tp +--enable-decoder-swa-bounded-replay +--enable-dense-mlp-attn-tp +--enable-dsa-cache-layer-split +--enable-dsa-fused-indexer +--enable-encoder-swa-bounded-replay +--enable-flexkv +--enable-layernorm-sp +--enable-lean-attention +--enable-linear-replayssm +--enable-linear-replayssm-spec +--enable-linker-mla-dedup +--enable-pd-role-switch +--enable-response-store +--enable-scattered-sconv +--enable-session-radix-cache +--enable-shared-experts-attn-tp +--enable-tp-lm-head-all-to-all +--enable-unified-cache-external-linker +--enable-w4a4-mxfp4-megamoe +--flexkv-config-file +--fuseep-mode +--gated-launch-port +--grpc-port +--grpc-response-timeout-secs +--hicache-host-memory-fraction +--hicache-host-memory-mode +--hicache-storage-prefetch-retry-max-attempts +--hicache-storage-prefetch-retry-poll-interval +--http2-initial-connection-window-size +--linear-attn-verify-backend +--linear-replayssm-cache-len +--mamba-max-states-per-path +--max-ep-size +--min-free-slots-delay +--mm-feature-transport +--mm-global-cache-backend +--mm-io-worker-num +--mm-preprocess-cache-size-mb +--mm-processor-worker-num +--otlp-service-name +--prefill-decode-interval +--prefill-kv-cache-dequant-dtype +--qsa-indexer-dtype +--radix-eviction-policy-config +--return-input-ids +--return-output-ids +--sampling-mask-max-tokens +--shared-experts-tp-size +--sidecar +--sidecar-args +--smg-grpc-mode +--spec-trace-dir +--speculative-domino-candidate-pool-size +--speculative-draft-kv-cache-dtype +--speculative-draft-sink-size +--speculative-dspark-align-verify-tokens-to-graph-tier +--speculative-dspark-block-size +--speculative-dspark-confidence-sts-path +--speculative-dspark-sps-table-path +--speculative-use-rejection-sampling +--startup-weight-load-mode +--swa-prefix-tails +--trust-mm-content-hashes +--trust-request-chat-template +--unified-cache-external-linker-backend +--uno-lora-path +--weight-cache-mode +--weight-cache-socket +--weight-cache-timeout diff --git a/test/registered/unit/server_args/test_server_args_docs_coverage.py b/test/registered/unit/server_args/test_server_args_docs_coverage.py new file mode 100644 index 0000000000..fa127755be --- /dev/null +++ b/test/registered/unit/server_args/test_server_args_docs_coverage.py @@ -0,0 +1,145 @@ +"""Every live ServerArgs flag needs a row in server_arguments.mdx and every flag +the doc names must still register. The allowlist may only shrink. +""" + +import argparse +import re +import unittest +from collections.abc import Iterable +from pathlib import Path + +from sglang.srt.arg_groups.argparse_actions import ( + DeprecatedAction, + DeprecatedAliasStoreAction, + DeprecatedStoreConstAction, + DeprecatedStoreTrueAction, +) +from sglang.srt.server_args import ServerArgs +from sglang.test.ci.ci_register import register_cpu_ci +from sglang.test.test_utils import CustomTestCase + +register_cpu_ci(est_time=5, suite="base-a-test-cpu") + +_DOC_DIR = Path(__file__).resolve().parents[4] / "docs" / "docs" / "advanced_features" +_DOC_PATH = _DOC_DIR / "server_arguments.mdx" +# Live flags with no row. May only shrink. Kept beside the doc, outside the +# main_package CI paths, so a PR that backfills rows runs only the CPU stage. +_UNDOCUMENTED_PATH = _DOC_DIR / "server_arguments_undocumented.txt" + +_DEPRECATED_ACTION_TYPES = ( + DeprecatedAction, + DeprecatedStoreTrueAction, + DeprecatedStoreConstAction, + DeprecatedAliasStoreAction, +) + +# Argument, Description, Defaults, Options. +_DOC_COLUMNS = 4 + +# Only delimited mentions count, so a prose wildcard like `--cuda-graph-*` +# never becomes a fabricated flag name. +_ROW_FLAG_RE = re.compile(r"`(--[a-zA-Z0-9][\w-]*)`|(--[a-zA-Z0-9][\w-]*)") + + +def _undocumented() -> frozenset[str]: + lines = _UNDOCUMENTED_PATH.read_text(encoding="utf-8").splitlines() + return frozenset( + line.strip() for line in lines if line.strip() and not line.startswith("#") + ) + + +_UNDOCUMENTED = _undocumented() + + +def _parser_actions() -> tuple[list[argparse.Action], list[argparse.Action]]: + parser = argparse.ArgumentParser(add_help=False) + ServerArgs.add_cli_args(parser) + live, deprecated = [], [] + for action in parser._actions: + (deprecated if isinstance(action, _DEPRECATED_ACTION_TYPES) else live).append( + action + ) + return live, deprecated + + +def _doc_rows() -> list[list[str]]: + text = _DOC_PATH.read_text(encoding="utf-8-sig") + rows = [ + re.findall(r"]*>(.*?)", row, re.S) + for row in re.findall(r"]*>(.*?)", text, re.S) + ] + # Header rows hold only cells. + return [cells for cells in rows if cells] + + +def _flags_in(cells: Iterable[str]) -> set[str]: + return { + match.group(1) or match.group(2) + for cell in cells + for match in _ROW_FLAG_RE.finditer(cell) + } + + +class TestServerArgsDocsCoverage(CustomTestCase): + @classmethod + def setUpClass(cls): + cls.live_actions, deprecated_actions = _parser_actions() + cls.rows = _doc_rows() + argument_column_flags = _flags_in(cells[0] for cells in cls.rows) + cls.uncovered = { + action.option_strings[0] + for action in cls.live_actions + # Any alias counts. + if argument_column_flags.isdisjoint(action.option_strings) + } + registered = { + o for a in cls.live_actions + deprecated_actions for o in a.option_strings + } + cls.stale = _flags_in(cell for cells in cls.rows for cell in cells) - registered + + def test_every_row_has_four_cells(self): + """Coverage reads only the first cell. A row the cell regex splits wrongly + can pass description text off as the Argument column and hide a gap.""" + misshapen = [cells[0][:80] for cells in self.rows if len(cells) != _DOC_COLUMNS] + self.assertFalse( + misshapen, + f"these rows do not have {_DOC_COLUMNS} cells, so their first cell may " + "not be the Argument column:\n " + "\n ".join(misshapen), + ) + + def test_no_new_undocumented_flags(self): + added = sorted(self.uncovered - _UNDOCUMENTED) + self.assertFalse( + added, + "these live flags have no row in server_arguments.mdx and are not " + "on the allow list. Add a row (lift the help text from the " + "field's Arg(help=...)) or if it is a deliberate omission, add " + f"it to {_UNDOCUMENTED_PATH.name}:\n " + "\n ".join(added), + ) + + def test_undocumented_allowlist_is_current(self): + live_options = {a.option_strings[0] for a in self.live_actions} + outdated = [] + for flag in sorted(_UNDOCUMENTED - self.uncovered): + reason = "now documented" if flag in live_options else "flag is gone" + outdated.append(f"{flag} ({reason})") + self.assertFalse( + outdated, + f"these entries in {_UNDOCUMENTED_PATH.name} are out of date. " + "Remove them from the file:\n " + "\n ".join(outdated), + ) + + def test_no_stale_rows(self): + stale = sorted(self.stale) + self.assertFalse( + stale, + "server_arguments.mdx names these flags but they no longer register " + "as a current or deprecated flag. The flag was renamed (possibly via " + "cli_name=) or removed, or its field has no CLI surface (no A[] " + "annotation, or Arg(no_cli=True)). Fix or delete the mention:\n " + + "\n ".join(stale), + ) + + +if __name__ == "__main__": + unittest.main()