[Test] Add a docs drift check for server_arguments.mdx (#38520)

Signed-off-by: Martin Hickey <martin.hickey@ie.ibm.com>
Co-authored-by: Cheng Wan <54331508+ch-wan@users.noreply.github.com>
Co-authored-by: Cheng Wan <cheng.wan@radixark.ai>
This commit is contained in:
Martin Hickey
2026-10-08 00:37:22 -07:00
committed by GitHub
co-authored by Cheng Wan Cheng Wan
parent 785005d21b
commit f795fe352d
6 changed files with 264 additions and 49 deletions
@@ -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 }} |"
+2 -2
View File
@@ -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:
+3
View File
@@ -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
@@ -780,12 +780,6 @@ Please consult the documentation below and [server_args.py](https://github.com/s
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`False`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>bool flag (set to enable)</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--custom-sigquit-handler`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>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.</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`None`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: str</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--batch-notify-size`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Number of streaming notifications to batch before yielding to the event loop. Reduces asyncio wakeup overhead under high concurrency.</td>
@@ -1611,6 +1605,12 @@ Combining `--enable-response-store` with `--disaggregation-mode=prefill` or `dec
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>The accept probability of a draft token is raised from its target probability p to min(1, p / threshold_acc).</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`1.0`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: float</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--speculative-use-block-verification`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Use block verification for EAGLE/EAGLE3/NEXTN on CUDA or ROCm (requires topk=1).</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`False`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: bool</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--speculative-token-map`</td>
@@ -2968,12 +2968,6 @@ This option does not disable required attention or MoE collectives, including ex
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>The input filename for dumping tensors</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`None`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: str</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--debug-tensor-dump-inject`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Inject the outputs from jax as the input of every layer.</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`False`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: str</td>
</tr>
</tbody>
</table>
@@ -3050,8 +3044,8 @@ This option does not disable required attention or MoE collectives, including ex
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>bool flag (set to enable)</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--optimistic-prefill-retries`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Number of optimistic prefill retries that will skip the bootstrap wait.</td>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--optimistic-prefill-attempts`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Number of optimistic prefill forward passes that skip the bootstrap wait.</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`0`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: int</td>
</tr>
@@ -3434,36 +3428,3 @@ This option does not disable required attention or MoE collectives, including ex
</tr>
</tbody>
</table>
## Deprecated arguments
<table style={{width: "100%", borderCollapse: "collapse", tableLayout: "fixed"}}>
<colgroup>
<col style={{width: "25%"}} />
<col style={{width: "25%"}} />
<col style={{width: "25%"}} />
<col style={{width: "25%"}} />
</colgroup>
<thead>
<tr style={{borderBottom: "2px solid #d55816"}}>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.02)"}}>Argument</th>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.05)"}}>Description</th>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.02)"}}>Defaults</th>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.05)"}}>Options</th>
</tr>
</thead>
<tbody>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--hybrid-kvcache-ratio`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>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)</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`None`</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Optional[float]</td>
</tr>
</tbody>
</table>
@@ -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
@@ -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-]*)`|<code>(--[a-zA-Z0-9][\w-]*)</code>")
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"<td[^>]*>(.*?)</td>", row, re.S)
for row in re.findall(r"<tr[^>]*>(.*?)</tr>", text, re.S)
]
# Header rows hold only <th> 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()