sphinx-dynamic-command-builder 0.1.0__tar.gz

sphinx_dynamic_command_builder-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+docs/_build/
+examples/_build/

sphinx_dynamic_command_builder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sphinx-dynamic-command-builder contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_dynamic_command_builder-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: sphinx-dynamic-command-builder
+Version: 0.1.0
+Summary: Interactive command builders for Sphinx documentation
+Project-URL: Homepage, https://github.com/Aionw/sphinx-dynamic-command-builder
+Project-URL: Repository, https://github.com/Aionw/sphinx-dynamic-command-builder
+Project-URL: Issues, https://github.com/Aionw/sphinx-dynamic-command-builder/issues
+Author: sphinx-dynamic-command-builder contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: command,directive,documentation,interactive,sphinx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6
+Requires-Dist: sphinx>=5
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2; extra == 'docs'
+Requires-Dist: sphinx-book-theme>=1; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# sphinx-dynamic-command-builder
+
+[![PyPI](https://img.shields.io/pypi/v/sphinx-dynamic-command-builder.svg)](https://pypi.org/project/sphinx-dynamic-command-builder/)
+
+Interactive command builders for Sphinx documentation.
+
+`sphinx-dynamic-command-builder` adds a `dynamic-command` directive that renders a small selector UI from YAML and updates a generated command in the browser. It is useful for docs that need to show command-line examples assembled from several independent choices.
+
+Demo: [GitHub Pages](https://aionw.github.io/sphinx-dynamic-command-builder/)
+
+## Install
+
+```bash
+pip install sphinx-dynamic-command-builder
+```
+
+Then enable the extension in `conf.py`:
+
+```python
+extensions = [
+    "sphinx_dynamic_command_builder",
+]
+```
+
+## Usage
+
+````md
+```{dynamic-command}
+base: python -m sglang.launch_server --model-path [model_path]
+format:
+  line_break: options
+  indent: "  "
+options:
+  - label: Topology
+    key: nodes
+    default: single
+    choices:
+      - label: Single node
+        value: single
+        args: --host 0.0.0.0 --port 30000
+      - label: Multi node
+        value: multi
+        args: --host 0.0.0.0 --port 30000 --disaggregation-ib-device mlx5_1
+```
+````
+
+Each option group is rendered as one selector row. Selecting a choice updates the generated command.
+
+## YAML schema
+
+See [Configuration](docs/configuration.md) for the full field reference and formatting rules.
+
+- `base`: base command string.
+- `command_label`: optional output label. Defaults to `Generated command`.
+- `format.line_break`: optional command wrapping mode. Use `options` to put each `--option` group on its own shell-continuation line, or `none` to render a single line. Defaults to `options`.
+- `format.indent`: optional indentation for continuation lines. Defaults to two spaces.
+- `options`: list of option groups.
+- `options[].label`: visible group label.
+- `options[].key`: stable group key.
+- `options[].default`: optional default choice value. Defaults to the first choice.
+- `options[].choices`: list of choices.
+- `choices[].label`: visible choice label.
+- `choices[].value`: stable choice value.
+- `choices[].env`: optional text prepended before the base command.
+- `choices[].args`: optional text appended after the base command.
+- `choices[].base`: optional replacement base command for this choice.
+
+## Development
+
+```bash
+uv venv
+uv pip install -e ".[test,docs]"
+pytest
+sphinx-build -M html docs docs/_build
+```

sphinx_dynamic_command_builder-0.1.0/README.md

@@ -0,0 +1,75 @@
+# sphinx-dynamic-command-builder
+
+[![PyPI](https://img.shields.io/pypi/v/sphinx-dynamic-command-builder.svg)](https://pypi.org/project/sphinx-dynamic-command-builder/)
+
+Interactive command builders for Sphinx documentation.
+
+`sphinx-dynamic-command-builder` adds a `dynamic-command` directive that renders a small selector UI from YAML and updates a generated command in the browser. It is useful for docs that need to show command-line examples assembled from several independent choices.
+
+Demo: [GitHub Pages](https://aionw.github.io/sphinx-dynamic-command-builder/)
+
+## Install
+
+```bash
+pip install sphinx-dynamic-command-builder
+```
+
+Then enable the extension in `conf.py`:
+
+```python
+extensions = [
+    "sphinx_dynamic_command_builder",
+]
+```
+
+## Usage
+
+````md
+```{dynamic-command}
+base: python -m sglang.launch_server --model-path [model_path]
+format:
+  line_break: options
+  indent: "  "
+options:
+  - label: Topology
+    key: nodes
+    default: single
+    choices:
+      - label: Single node
+        value: single
+        args: --host 0.0.0.0 --port 30000
+      - label: Multi node
+        value: multi
+        args: --host 0.0.0.0 --port 30000 --disaggregation-ib-device mlx5_1
+```
+````
+
+Each option group is rendered as one selector row. Selecting a choice updates the generated command.
+
+## YAML schema
+
+See [Configuration](docs/configuration.md) for the full field reference and formatting rules.
+
+- `base`: base command string.
+- `command_label`: optional output label. Defaults to `Generated command`.
+- `format.line_break`: optional command wrapping mode. Use `options` to put each `--option` group on its own shell-continuation line, or `none` to render a single line. Defaults to `options`.
+- `format.indent`: optional indentation for continuation lines. Defaults to two spaces.
+- `options`: list of option groups.
+- `options[].label`: visible group label.
+- `options[].key`: stable group key.
+- `options[].default`: optional default choice value. Defaults to the first choice.
+- `options[].choices`: list of choices.
+- `choices[].label`: visible choice label.
+- `choices[].value`: stable choice value.
+- `choices[].env`: optional text prepended before the base command.
+- `choices[].args`: optional text appended after the base command.
+- `choices[].base`: optional replacement base command for this choice.
+
+## Development
+
+```bash
+uv venv
+uv pip install -e ".[test,docs]"
+pytest
+sphinx-build -M html docs docs/_build
+```

sphinx_dynamic_command_builder-0.1.0/docs/conf.py

@@ -0,0 +1,7 @@
+extensions = [
+    "myst_parser",
+    "sphinx_dynamic_command_builder",
+]
+
+project = "sphinx-dynamic-command-builder"
+html_theme = "sphinx_book_theme"

sphinx_dynamic_command_builder-0.1.0/docs/configuration.md

@@ -0,0 +1,93 @@
+# Configuration
+
+The `dynamic-command` directive reads a YAML mapping. The YAML describes the
+base command, the generated command format, and the option groups rendered as
+selectors.
+
+## Minimal Example
+
+````md
+```{dynamic-command}
+base: python -m sglang.launch_server --model-path [model_path]
+options:
+  - label: Topology
+    key: nodes
+    default: single
+    choices:
+      - label: Single node
+        value: single
+        args: --host 0.0.0.0 --port 30000
+      - label: Multi node
+        value: multi
+        args: --host 0.0.0.0 --port 30000 --disaggregation-ib-device mlx5_1
+```
+````
+
+## Top-Level Fields
+
+- `base`: required string. The default command before selected choices add or replace anything.
+- `command_label`: optional string. Label shown above the generated command. Defaults to `Generated command`.
+- `format`: optional mapping. Controls how the generated command is displayed.
+- `options`: required non-empty list. Each item defines one selector row.
+
+## Format Fields
+
+`format.line_break` controls command wrapping:
+
+- `options`: default. Render the command as shell-continuation lines and put each `--option` group on its own line.
+- `none`: render the command as a single line.
+
+`format.indent` controls indentation for continuation lines. It defaults to two spaces.
+
+Example:
+
+```yaml
+format:
+  line_break: options
+  indent: "  "
+```
+
+This renders:
+
+```bash
+python -m sglang.launch_server \
+  --model-path [model_path] \
+  --host 0.0.0.0 \
+  --port 30000
+```
+
+Use `line_break: none` when the exact single-line command matters:
+
+```yaml
+format:
+  line_break: none
+```
+
+## Option Fields
+
+Each item in `options` defines one selector group:
+
+- `options[].label`: required string. Visible group label.
+- `options[].key`: required string. Stable key used to track the selected choice.
+- `options[].default`: optional string. Default choice value. Defaults to the first choice.
+- `options[].choices`: required non-empty list. Available choices for the group.
+
+Each item in `choices` defines one selectable command fragment:
+
+- `choices[].label`: required string. Visible button label.
+- `choices[].value`: required string. Stable choice value.
+- `choices[].env`: optional string. Prepended before the command when selected.
+- `choices[].args`: optional string. Appended after the command when selected.
+- `choices[].base`: optional string. Replaces the top-level `base` command when selected.
+
+## Command Assembly
+
+The generated command is assembled in this order:
+
+1. Selected `env` fragments.
+2. The active command, either top-level `base` or the selected choice `base`.
+3. Selected `args` fragments in option group order.
+
+With `format.line_break: options`, tokens beginning with `--` start a new
+continuation line. Values following an option stay on the same line as that
+option.

sphinx_dynamic_command_builder-0.1.0/docs/index.md

@@ -0,0 +1,49 @@
+# sphinx-dynamic-command-builder
+
+```{toctree}
+:maxdepth: 2
+
+configuration
+```
+
+```{dynamic-command}
+base: python -m sglang.launch_server --model-path [model_path]
+format:
+  line_break: options
+  indent: "  "
+options:
+  - label: Integration path
+    key: path
+    default: hicache
+    choices:
+      - label: HiCache L3
+        value: hicache
+        env: MOONCAKE_MASTER=127.0.0.1:50051
+        args: --enable-hierarchical-cache --hicache-storage-backend mooncake
+      - label: PD disaggregation
+        value: pd
+        args: --disaggregation-mode prefill
+  - label: Topology
+    key: nodes
+    default: single
+    choices:
+      - label: Single node
+        value: single
+        args: --host 0.0.0.0 --port 30000
+      - label: Multi node
+        value: multi
+        args: --host 0.0.0.0 --port 30000 --disaggregation-ib-device mlx5_1
+  - label: Parallelism
+    key: tp
+    default: "4"
+    choices:
+      - label: TP 1
+        value: "1"
+        args: --tp-size 1
+      - label: TP 4
+        value: "4"
+        args: --tp-size 4
+      - label: TP 8
+        value: "8"
+        args: --tp-size 8
+```

sphinx_dynamic_command_builder-0.1.0/examples/README.md

@@ -0,0 +1,14 @@
+# Interactive example
+
+This directory is a minimal Sphinx project that uses the local
+`sphinx_dynamic_command_builder` extension.
+
+Build it from the repository root:
+
+```bash
+sphinx-build -M html examples examples/_build
+```
+
+Then open `examples/_build/html/index.html` in a browser. The generated page
+loads the extension's CSS and JavaScript through Sphinx instead of relying on a
+hand-written HTML mockup.

sphinx_dynamic_command_builder-0.1.0/examples/_static/example.css

@@ -0,0 +1,64 @@
+:root {
+  --example-bg: #f7f8fb;
+  --example-text: #1f2328;
+  --example-muted: #59636e;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  background: var(--example-bg);
+}
+
+body {
+  background: var(--example-bg);
+  color: var(--example-text);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  line-height: 1.5;
+  margin: 0;
+}
+
+a.headerlink {
+  display: none;
+}
+
+div.related,
+div.sphinxsidebar,
+div.footer,
+div.clearer {
+  display: none;
+}
+
+div.document {
+  margin: 0 auto;
+  max-width: 1040px;
+  padding: 48px 20px 64px;
+}
+
+div.documentwrapper,
+div.bodywrapper {
+  float: none;
+  margin: 0;
+}
+
+div.body {
+  margin: 0;
+  min-width: 0;
+  max-width: none;
+}
+
+h1 {
+  font-size: clamp(2rem, 5vw, 3.7rem);
+  letter-spacing: 0;
+  line-height: 1.05;
+  margin: 0 0 14px;
+}
+
+p {
+  color: var(--example-muted);
+  font-size: 1.04rem;
+  margin: 0 0 1.5rem;
+  max-width: 700px;
+}

sphinx_dynamic_command_builder-0.1.0/examples/conf.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+project = "sphinx-dynamic-command-builder example"
+extensions = [
+    "sphinx_dynamic_command_builder",
+]
+
+html_title = project
+html_theme = "basic"
+html_static_path = ["_static"]
+html_css_files = ["example.css"]
+html_sidebars = {"**": []}
+html_show_sourcelink = False
+html_use_index = False
+exclude_patterns = ["_build"]

sphinx_dynamic_command_builder-0.1.0/examples/index.rst

@@ -0,0 +1,57 @@
+sphinx-dynamic-command-builder example
+==============================
+
+This page is built by Sphinx and renders the command builder through the
+``sphinx_dynamic_command_builder`` extension.
+
+.. dynamic-command::
+
+   base: python -m sglang.launch_server --model-path [model_path]
+   command_label: Generated command
+   format:
+     line_break: options
+     indent: "  "
+   options:
+     - label: Integration path
+       key: path
+       default: hicache
+       choices:
+         - label: HiCache L3
+           value: hicache
+           env: MOONCAKE_MASTER=127.0.0.1:50051
+           args: --enable-hierarchical-cache --hicache-storage-backend mooncake
+         - label: PD disaggregation
+           value: pd
+           args: --disaggregation-mode prefill
+     - label: Topology
+       key: nodes
+       default: single
+       choices:
+         - label: Single node
+           value: single
+           args: --host 0.0.0.0 --port 30000
+         - label: Multi node
+           value: multi
+           args: --host 0.0.0.0 --port 30000 --disaggregation-ib-device mlx5_1
+     - label: Parallelism
+       key: tp
+       default: "4"
+       choices:
+         - label: TP 1
+           value: "1"
+           args: --tp-size 1
+         - label: TP 4
+           value: "4"
+           args: --tp-size 4
+         - label: TP 8
+           value: "8"
+           args: --tp-size 8
+     - label: Runtime
+       key: runtime
+       default: python
+       choices:
+         - label: Python module
+           value: python
+         - label: uv run
+           value: uv
+           base: uv run python -m sglang.launch_server --model-path [model_path]

sphinx_dynamic_command_builder-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinx-dynamic-command-builder"
+version = "0.1.0"
+description = "Interactive command builders for Sphinx documentation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+  { name = "sphinx-dynamic-command-builder contributors" },
+]
+keywords = ["sphinx", "documentation", "directive", "command", "interactive"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+  "PyYAML>=6",
+  "Sphinx>=5",
+]
+
+[project.optional-dependencies]
+docs = [
+  "myst-parser>=2",
+  "sphinx-book-theme>=1",
+]
+test = [
+  "pytest>=7",
+]
+
+[project.urls]
+Homepage = "https://github.com/Aionw/sphinx-dynamic-command-builder"
+Repository = "https://github.com/Aionw/sphinx-dynamic-command-builder"
+Issues = "https://github.com/Aionw/sphinx-dynamic-command-builder/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_dynamic_command_builder"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/docs",
+  "/examples",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]

sphinx_dynamic_command_builder-0.1.0/src/sphinx_dynamic_command_builder/__init__.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from sphinx.util.fileutil import copy_asset
+
+from .directive import DynamicCommandDirective
+
+__version__ = "0.1.0"
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def _copy_static_assets(app, exc):
+    if exc is not None or app.builder.format != "html":
+        return
+
+    static_out = Path(app.outdir) / "_static"
+    copy_asset(str(STATIC_DIR / "sphinx-dynamic-command-builder.css"), str(static_out))
+    copy_asset(str(STATIC_DIR / "sphinx-dynamic-command-builder.js"), str(static_out))
+
+
+def setup(app):
+    app.add_directive("dynamic-command", DynamicCommandDirective)
+    app.add_css_file("sphinx-dynamic-command-builder.css")
+    app.add_js_file("sphinx-dynamic-command-builder.js")
+    app.connect("build-finished", _copy_static_assets)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_dynamic_command_builder-0.1.0/src/sphinx_dynamic_command_builder/directive.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from html import escape
+from typing import Any
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+import yaml
+
+
+def _as_str(value: Any, field: str) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a string")
+    return value
+
+
+def _choice_button(group_key: str, group_default: str, choice: dict[str, Any]) -> str:
+    label = _as_str(choice.get("label"), "choice.label")
+    value = _as_str(choice.get("value"), "choice.value")
+    if not label:
+        raise ValueError("choice.label is required")
+    if not value:
+        raise ValueError("choice.value is required")
+
+    attrs = {
+        "class": "sdc-button",
+        "type": "button",
+        "data-sdc-option": group_key,
+        "data-sdc-value": value,
+    }
+
+    command_base = _as_str(choice.get("base"), "choice.base")
+    env = _as_str(choice.get("env"), "choice.env")
+    args = _as_str(choice.get("args"), "choice.args")
+    if command_base:
+        attrs["data-sdc-base"] = command_base
+    if env:
+        attrs["data-sdc-env"] = env
+    if args:
+        attrs["data-sdc-args"] = args
+    if value == group_default:
+        attrs["data-sdc-default"] = "true"
+
+    rendered_attrs = " ".join(
+        f'{escape(name)}="{escape(attr_value, quote=True)}"'
+        for name, attr_value in attrs.items()
+    )
+    return f"<button {rendered_attrs}>{escape(label)}</button>"
+
+
+def _option_group(group: dict[str, Any]) -> str:
+    label = _as_str(group.get("label"), "options.label")
+    key = _as_str(group.get("key"), "options.key")
+    default = _as_str(group.get("default"), "options.default")
+    choices = group.get("choices")
+
+    if not label:
+        raise ValueError("options.label is required")
+    if not key:
+        raise ValueError("options.key is required")
+    if not isinstance(choices, list) or not choices:
+        raise ValueError(f"options.{key}.choices must be a non-empty list")
+
+    if not default:
+        default = _as_str(choices[0].get("value"), "choice.value")
+
+    buttons = "\n".join(_choice_button(key, default, choice) for choice in choices)
+    return f"""
+    <div class="sdc-group">
+      <div class="sdc-label">{escape(label)}</div>
+      <div class="sdc-buttons">
+        {buttons}
+      </div>
+    </div>
+"""
+
+
+def _format_attrs(config: dict[str, Any]) -> dict[str, str]:
+    format_config = config.get("format", {})
+    if format_config is None:
+        format_config = {}
+    if not isinstance(format_config, dict):
+        raise ValueError("format must be a YAML mapping")
+
+    line_break = _as_str(format_config.get("line_break", "options"), "format.line_break")
+    if line_break not in {"options", "none"}:
+        raise ValueError("format.line_break must be one of: options, none")
+
+    indent = _as_str(format_config.get("indent", "  "), "format.indent")
+
+    return {
+        "data-sdc-line-break": line_break,
+        "data-sdc-indent": indent,
+    }
+
+
+class DynamicCommandDirective(Directive):
+    """Render a selector-driven command generator from YAML content."""
+
+    has_content = True
+
+    def run(self) -> list[nodes.Node]:
+        try:
+            config = yaml.safe_load("\n".join(self.content)) or {}
+            if not isinstance(config, dict):
+                raise ValueError("dynamic-command content must be a YAML mapping")
+
+            base = _as_str(config.get("base"), "base")
+            if not base:
+                raise ValueError("base is required")
+
+            groups = config.get("options")
+            if not isinstance(groups, list) or not groups:
+                raise ValueError("options must be a non-empty list")
+
+            command_label = _as_str(
+                config.get("command_label", "Generated command"), "command_label"
+            )
+            format_attrs = _format_attrs(config)
+            rendered_format_attrs = " ".join(
+                f'{escape(name)}="{escape(value, quote=True)}"'
+                for name, value in format_attrs.items()
+            )
+            rendered_groups = "\n".join(_option_group(group) for group in groups)
+        except Exception as exc:
+            error = self.state_machine.reporter.error(
+                f"dynamic-command: {exc}",
+                line=self.lineno,
+            )
+            return [error]
+
+        html = f"""
+<div class="sdc-card">
+  <div data-sdc>
+    <div class="sdc-controls">
+      {rendered_groups}
+    </div>
+    <div class="sdc-command">
+      <div class="sdc-command-label">{escape(command_label)}</div>
+      <pre><code class="language-bash" data-sdc-output data-sdc-base="{escape(base, quote=True)}" {rendered_format_attrs}></code></pre>
+    </div>
+  </div>
+</div>
+"""
+        return [nodes.raw("", html, format="html")]

sphinx_dynamic_command_builder-0.1.0/src/sphinx_dynamic_command_builder/static/sphinx-dynamic-command-builder.css

@@ -0,0 +1,105 @@
+.sdc-card {
+  background: var(--pst-color-background, #fff);
+  border: 1px solid var(--pst-color-border, #d8dee4);
+  border-radius: 8px;
+  box-shadow: 0 1px 2px rgb(0 0 0 / 6%);
+  margin: 1.5rem 0;
+  overflow: hidden;
+}
+
+.sdc-controls {
+  background: color-mix(in srgb, var(--pst-color-surface, #f6f8fa) 96%, var(--pst-color-primary, #0969da) 4%);
+  border-bottom: 1px solid var(--pst-color-border, #d8dee4);
+  display: grid;
+  gap: 0;
+  padding: 0.35rem 1rem;
+}
+
+.sdc-group {
+  align-items: center;
+  border-bottom: 1px solid var(--pst-color-border, #d8dee4);
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(120px, 180px) 1fr;
+  padding: 0.65rem 0;
+}
+
+.sdc-group:last-child {
+  border-bottom: 0;
+}
+
+.sdc-label,
+.sdc-command-label {
+  color: var(--pst-color-text-muted, #57606a);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0;
+  line-height: 1.2;
+}
+
+.sdc-buttons {
+  background: var(--pst-color-background, #fff);
+  border: 1px solid var(--pst-color-border, #d8dee4);
+  border-radius: 7px;
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+  max-width: 100%;
+  padding: 0.25rem;
+  width: max-content;
+}
+
+.sdc-button {
+  background: transparent;
+  border: 0;
+  border-radius: 5px;
+  color: var(--pst-color-text-base, #24292f);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.9rem;
+  line-height: 1.2;
+  padding: 0.42rem 0.68rem;
+  transition: background-color 120ms ease, color 120ms ease, box-shadow 120ms ease;
+}
+
+.sdc-button.is-selected {
+  background: var(--pst-color-primary, #0969da);
+  box-shadow: 0 1px 2px rgb(0 0 0 / 12%);
+  color: var(--pst-color-on-primary, #fff);
+}
+
+.sdc-command {
+  background: var(--pst-color-background, #fff);
+  padding: 1rem;
+}
+
+.sdc-command-label {
+  margin-bottom: 0.5rem;
+}
+
+.sdc-command pre {
+  border: 1px solid var(--pst-color-border, #d8dee4);
+  border-radius: 7px;
+  margin: 0;
+  overflow-x: auto;
+  white-space: pre;
+}
+
+.sdc-command code {
+  font-size: 0.86rem;
+  line-height: 1.45;
+  white-space: pre;
+}
+
+@media (max-width: 640px) {
+  .sdc-group {
+    align-items: start;
+    gap: 0.45rem;
+    grid-template-columns: 1fr;
+  }
+
+  .sdc-buttons {
+    width: 100%;
+  }
+}
+

sphinx_dynamic_command_builder-0.1.0/src/sphinx_dynamic_command_builder/static/sphinx-dynamic-command-builder.js

@@ -0,0 +1,147 @@
+(() => {
+  function tokenizeCommand(command) {
+    return command.match(/"[^"]*"|'[^']*'|\S+/g) || [];
+  }
+
+  function splitCommandParts(command) {
+    const tokens = tokenizeCommand(command);
+    const firstOption = tokens.findIndex((token) => token.startsWith("--"));
+
+    if (firstOption === -1) {
+      return {
+        prefix: tokens.join(" "),
+        options: [],
+      };
+    }
+
+    return {
+      prefix: tokens.slice(0, firstOption).join(" "),
+      options: groupOptionTokens(tokens.slice(firstOption)),
+    };
+  }
+
+  function groupOptionTokens(tokens) {
+    const groups = [];
+    let group = [];
+
+    tokens.forEach((token) => {
+      if (token.startsWith("--") && group.length) {
+        groups.push(group.join(" "));
+        group = [token];
+        return;
+      }
+
+      group.push(token);
+    });
+
+    if (group.length) {
+      groups.push(group.join(" "));
+    }
+
+    return groups;
+  }
+
+  function formatCommand(env, command, args, config) {
+    if (config.lineBreak === "none") {
+      return [...env, command, ...args].filter(Boolean).join(" ");
+    }
+
+    const commandParts = splitCommandParts(command);
+    const lines = [
+      [...env, commandParts.prefix].filter(Boolean).join(" "),
+      ...commandParts.options,
+      ...args.flatMap((arg) => groupOptionTokens(tokenizeCommand(arg))),
+    ].filter(Boolean);
+
+    return lines
+      .map((line, index) => {
+        const continuation = index < lines.length - 1 ? " \\" : "";
+        const indent = index === 0 ? "" : config.indent;
+        return `${indent}${line}${continuation}`;
+      })
+      .join("\n");
+  }
+
+  function readState(panel) {
+    const keys = Array.from(
+      new Set(
+        Array.from(panel.querySelectorAll("[data-sdc-option]")).map((option) =>
+          option.getAttribute("data-sdc-option")
+        )
+      )
+    );
+
+    return keys.reduce((state, key) => {
+      const selected = panel.querySelector(
+        `[data-sdc-option="${key}"][data-sdc-default="true"]`
+      );
+      const first = panel.querySelector(`[data-sdc-option="${key}"]`);
+      state[key] = (selected || first)?.getAttribute("data-sdc-value") || "";
+      return state;
+    }, {});
+  }
+
+  function updatePanel(panel, state) {
+    panel.querySelectorAll("[data-sdc-option]").forEach((option) => {
+      const key = option.getAttribute("data-sdc-option");
+      const value = option.getAttribute("data-sdc-value");
+      const isSelected = state[key] === value;
+
+      option.classList.toggle("is-selected", isSelected);
+      option.setAttribute("aria-pressed", isSelected ? "true" : "false");
+    });
+
+    panel.querySelectorAll("[data-sdc-output]").forEach((output) => {
+      const env = [];
+      const args = [];
+      let command = output.getAttribute("data-sdc-base") || "";
+
+      Object.entries(state).forEach(([key, value]) => {
+        const selected = Array.from(
+          panel.querySelectorAll(`[data-sdc-option="${key}"]`)
+        ).find((option) => option.getAttribute("data-sdc-value") === value);
+
+        if (!selected) {
+          return;
+        }
+
+        const nextBase = selected.getAttribute("data-sdc-base");
+        const nextEnv = selected.getAttribute("data-sdc-env");
+        const nextArgs = selected.getAttribute("data-sdc-args");
+
+        if (nextBase) {
+          command = nextBase;
+        }
+        if (nextEnv) {
+          env.push(nextEnv);
+        }
+        if (nextArgs) {
+          args.push(nextArgs);
+        }
+      });
+
+      output.textContent = formatCommand(env, command, args, {
+        indent: output.getAttribute("data-sdc-indent") || "  ",
+        lineBreak: output.getAttribute("data-sdc-line-break") || "options",
+      });
+    });
+  }
+
+  function setupPanel(panel) {
+    const state = readState(panel);
+
+    panel.querySelectorAll("[data-sdc-option]").forEach((option) => {
+      option.addEventListener("click", () => {
+        state[option.getAttribute("data-sdc-option")] =
+          option.getAttribute("data-sdc-value");
+        updatePanel(panel, state);
+      });
+    });
+
+    updatePanel(panel, state);
+  }
+
+  document.addEventListener("DOMContentLoaded", () => {
+    document.querySelectorAll("[data-sdc]").forEach(setupPanel);
+  });
+})();

sphinx_dynamic_command_builder-0.1.0/tests/test_directive.py

@@ -0,0 +1,289 @@
+import pytest
+from docutils import nodes
+from docutils.core import publish_doctree
+from docutils.parsers.rst import directives
+
+import sphinx_dynamic_command_builder as extension
+from sphinx_dynamic_command_builder.directive import (
+    DynamicCommandDirective,
+    _choice_button,
+    _format_attrs,
+    _option_group,
+)
+
+
+directives.register_directive("dynamic-command", DynamicCommandDirective)
+
+
+def render_dynamic_command(content: str) -> str:
+    indented = "\n".join(f"   {line}" if line else "" for line in content.splitlines())
+    doctree = publish_doctree(f".. dynamic-command::\n\n{indented}\n")
+    raw_nodes = list(doctree.findall(nodes.raw))
+    assert len(raw_nodes) == 1
+    return raw_nodes[0].astext()
+
+
+def render_dynamic_command_error(content: str) -> str:
+    indented = "\n".join(f"   {line}" if line else "" for line in content.splitlines())
+    doctree = publish_doctree(f".. dynamic-command::\n\n{indented}\n")
+    messages = list(doctree.findall(nodes.system_message))
+    assert len(messages) == 1
+    return messages[0].astext()
+
+
+def test_directive_registered_importable():
+    assert DynamicCommandDirective.has_content is True
+
+
+def test_format_attrs_defaults_to_option_line_breaks():
+    assert _format_attrs({}) == {
+        "data-sdc-line-break": "options",
+        "data-sdc-indent": "  ",
+    }
+
+
+def test_format_attrs_rejects_unknown_line_break_mode():
+    with pytest.raises(ValueError, match="format.line_break"):
+        _format_attrs({"format": {"line_break": "always"}})
+
+
+def test_directive_renders_configured_command_builder_html():
+    html = render_dynamic_command(
+        """
+base: python -m tool --model "a b"
+command_label: Run <now> & "fast"
+format:
+  line_break: none
+  indent: "    "
+options:
+  - label: Mode <select>
+    key: mode
+    default: fast
+    choices:
+      - label: Fast & safe
+        value: fast
+        env: CUDA_VISIBLE_DEVICES=0
+        args: --batch-size 4 --name "x y"
+      - label: Slow "quoted"
+        value: slow
+        base: python -m slow
+        args: --debug
+""".strip()
+    )
+
+    assert 'data-sdc-base="python -m tool --model &quot;a b&quot;"' in html
+    assert 'data-sdc-line-break="none"' in html
+    assert 'data-sdc-indent="    "' in html
+    assert "Run &lt;now&gt; &amp; &quot;fast&quot;" in html
+    assert "Mode &lt;select&gt;" in html
+    assert 'data-sdc-option="mode"' in html
+    assert 'data-sdc-value="fast"' in html
+    assert 'data-sdc-default="true"' in html
+    assert 'data-sdc-env="CUDA_VISIBLE_DEVICES=0"' in html
+    assert 'data-sdc-args="--batch-size 4 --name &quot;x y&quot;"' in html
+    assert 'data-sdc-base="python -m slow"' in html
+    assert "Slow &quot;quoted&quot;" in html
+
+
+@pytest.mark.parametrize(
+    ("content", "message"),
+    [
+        ("- item", "dynamic-command content must be a YAML mapping"),
+        ("options: []", "base is required"),
+        ("base: run\noptions: []", "options must be a non-empty list"),
+        (
+            """
+base: run
+options:
+  - key: mode
+    choices:
+      - label: Fast
+        value: fast
+""".strip(),
+            "options.label is required",
+        ),
+        (
+            """
+base: run
+options:
+  - label: Mode
+    choices:
+      - label: Fast
+        value: fast
+""".strip(),
+            "options.key is required",
+        ),
+        (
+            """
+base: run
+options:
+  - label: Mode
+    key: mode
+    choices: []
+""".strip(),
+            "options.mode.choices must be a non-empty list",
+        ),
+        (
+            """
+base: run
+options:
+  - label: Mode
+    key: mode
+    choices:
+      - value: fast
+""".strip(),
+            "choice.label is required",
+        ),
+        (
+            """
+base: run
+options:
+  - label: Mode
+    key: mode
+    choices:
+      - label: Fast
+""".strip(),
+            "choice.value is required",
+        ),
+    ],
+)
+def test_directive_reports_configuration_errors(content, message):
+    assert message in render_dynamic_command_error(content)
+
+
+def test_format_attrs_accepts_explicit_options():
+    assert _format_attrs({"format": {"line_break": "none", "indent": "    "}}) == {
+        "data-sdc-line-break": "none",
+        "data-sdc-indent": "    ",
+    }
+
+
+@pytest.mark.parametrize(
+    ("config", "message"),
+    [
+        ({"format": []}, "format must be a YAML mapping"),
+        ({"format": {"indent": 2}}, "format.indent must be a string"),
+    ],
+)
+def test_format_attrs_rejects_invalid_format_config(config, message):
+    with pytest.raises(ValueError, match=message):
+        _format_attrs(config)
+
+
+def test_option_group_defaults_to_first_choice():
+    html = _option_group(
+        {
+            "label": "Mode",
+            "key": "mode",
+            "choices": [
+                {"label": "Fast", "value": "fast"},
+                {"label": "Slow", "value": "slow"},
+            ],
+        }
+    )
+
+    assert 'data-sdc-value="fast" data-sdc-default="true"' in html
+    assert 'data-sdc-value="slow" data-sdc-default="true"' not in html
+
+
+def test_choice_button_escapes_attribute_and_label_values():
+    html = _choice_button(
+        "mode",
+        "fast",
+        {
+            "label": "Fast <safe>",
+            "value": "fast",
+            "env": 'A="1&2"',
+            "args": '--name "x<y>"',
+            "base": "run <tool>",
+        },
+    )
+
+    assert "Fast &lt;safe&gt;" in html
+    assert 'data-sdc-env="A=&quot;1&amp;2&quot;"' in html
+    assert 'data-sdc-args="--name &quot;x&lt;y&gt;&quot;"' in html
+    assert 'data-sdc-base="run &lt;tool&gt;"' in html
+
+
+def test_setup_registers_directive_assets_and_build_hook():
+    class FakeApp:
+        def __init__(self):
+            self.directives = []
+            self.css_files = []
+            self.js_files = []
+            self.events = []
+
+        def add_directive(self, name, directive):
+            self.directives.append((name, directive))
+
+        def add_css_file(self, filename):
+            self.css_files.append(filename)
+
+        def add_js_file(self, filename):
+            self.js_files.append(filename)
+
+        def connect(self, event, callback):
+            self.events.append((event, callback))
+
+    app = FakeApp()
+
+    metadata = extension.setup(app)
+
+    assert app.directives == [("dynamic-command", DynamicCommandDirective)]
+    assert app.css_files == ["sphinx-dynamic-command-builder.css"]
+    assert app.js_files == ["sphinx-dynamic-command-builder.js"]
+    assert app.events == [("build-finished", extension._copy_static_assets)]
+    assert metadata == {
+        "version": extension.__version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
+
+
+def test_copy_static_assets_copies_files_for_html_build(tmp_path, monkeypatch):
+    copied = []
+
+    def fake_copy_asset(src, dst):
+        copied.append((src, dst))
+
+    class FakeBuilder:
+        format = "html"
+
+    class FakeApp:
+        builder = FakeBuilder()
+        outdir = tmp_path
+
+    monkeypatch.setattr(extension, "copy_asset", fake_copy_asset)
+
+    extension._copy_static_assets(FakeApp(), None)
+
+    assert copied == [
+        (
+            str(extension.STATIC_DIR / "sphinx-dynamic-command-builder.css"),
+            str(tmp_path / "_static"),
+        ),
+        (
+            str(extension.STATIC_DIR / "sphinx-dynamic-command-builder.js"),
+            str(tmp_path / "_static"),
+        ),
+    ]
+
+
+@pytest.mark.parametrize(("builder_format", "exc"), [("latex", None), ("html", Exception())])
+def test_copy_static_assets_skips_non_html_or_failed_build(
+    tmp_path, monkeypatch, builder_format, exc
+):
+    copied = []
+
+    class FakeBuilder:
+        format = builder_format
+
+    class FakeApp:
+        builder = FakeBuilder()
+        outdir = tmp_path
+
+    monkeypatch.setattr(extension, "copy_asset", lambda src, dst: copied.append((src, dst)))
+
+    extension._copy_static_assets(FakeApp(), exc)
+
+    assert copied == []