sphinx-dynamic-command-builder 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+sphinx_dynamic_command_builder/__init__.py,sha256=ctjvd-HhxRzbEljl1EEte7B7n65bfVKBqbqke6vXHms,934
+sphinx_dynamic_command_builder/directive.py,sha256=jxetw9bhL0nn3HmHTBWPGuxwRdjZ08wbILNuK8ZpjAw,4782
+sphinx_dynamic_command_builder/static/sphinx-dynamic-command-builder.css,sha256=U0P1jYKcaGIdk7WRsCckPkD1-6jbjIx_XbtQM6L17_k,2154
+sphinx_dynamic_command_builder/static/sphinx-dynamic-command-builder.js,sha256=T-wQQgVhUxYccURU1_xG2sjqbu40_nVeNfHe_aaAX28,4183
+sphinx_dynamic_command_builder-0.1.0.dist-info/METADATA,sha256=fQoxaSXPnjQk2c5US_gTIbUB_fovP7oPKFGzyaIwYG0,3959
+sphinx_dynamic_command_builder-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sphinx_dynamic_command_builder-0.1.0.dist-info/licenses/LICENSE,sha256=ZJcV9uUBseT13kS5cA9M3EqVprlFoJ2Fnm5qj_E80FA,1100
+sphinx_dynamic_command_builder-0.1.0.dist-info/RECORD,,

sphinx_dynamic_command_builder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

sphinx_dynamic_command_builder-0.1.0.dist-info/licenses/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.