Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Make the generated command reference easier to browse (#5237) (#5721)

Victor Santos Oliveiraecf57d131a26
diff --git a/xtask/src/book.rs b/xtask/src/book.rs
index 03311f7bce..5a301fbb43 100644
--- a/xtask/src/book.rs
+++ b/xtask/src/book.rs
@@ -82,43 +82,210 @@ fn json_files(dir: &Path) -> Result<Vec<std::path::PathBuf>, String> {
/// The command reference page: one section per toolbar tab and panel, in registry order.
fn reference(cmds: &[Value]) -> String {
- let s = |c: &Value, k: &str| c[k].as_str().unwrap_or_default().to_string();
let mut md = format!(
- "# Command reference\n\nGenerated by `cargo xtask book` from `solidcraft-cli commands` ({} commands). Every command runs the same \
- way from the toolbar, a script, `solidcraft-cli exec <id> '<json>'`, the control channel and MCP. Parameters marked `?` are \
- optional; `expr` is a number or an expression with units.\n",
+ "# Command reference\n\nBrowse commands by their names and default keyboard shortcuts. \
+ Entries are organized by command group and panel; ungrouped commands follow by area.\n\n\
+ For step-by-step instructions, start with the [window tour](../guide/ui-tour.md), \
+ [sketching guide](../guide/sketching.md) or [solid features guide](../guide/features.md). \
+ Each entry links to a related guide when one is available.\n\n\
+ Expand **Automation details** for the command ID and parameters used by scripts, the CLI and MCP. \
+ In that notation, `?` marks an optional parameter and `expr` means a number or an expression with units.\n\n\
+ This catalog is generated from `solidcraft-cli commands` by `cargo xtask book` ({} commands).\n",
cmds.len()
);
let mut sections: Vec<(String, Vec<&Value>)> = Vec::new();
for tab in TABS {
- for c in cmds.iter().filter(|c| s(c, "tab") == *tab) {
- let title = format!("{tab} › {}", s(c, "panel"));
+ for c in cmds.iter().filter(|c| command_text(c, "tab") == *tab) {
+ let panel = command_text(c, "panel").trim();
+ let title = if panel.is_empty() { tab.to_string() } else { format!("{tab} › {panel}") };
add(&mut sections, title, c);
}
}
- for c in cmds.iter().filter(|c| !TABS.contains(&s(c, "tab").as_str())) {
- let id = s(c, "id");
- let prefix = id.split('.').next().unwrap_or_default().to_string();
- add(&mut sections, format!("Other: {prefix}.*"), c);
+ for c in cmds.iter().filter(|c| !TABS.contains(&command_text(c, "tab"))) {
+ let prefix = command_text(c, "id").split('.').next().filter(|s| !s.is_empty());
+ let title = prefix.map_or_else(|| "Other commands".into(), |area| format!("Other commands: {area}"));
+ add(&mut sections, title, c);
}
for (title, list) in sections {
- md.push_str(&format!("\n## {title}\n\n"));
+ md.push_str(&format!("\n## {}\n\n", prose(&title)));
for c in list {
- let key = c["shortcut"].as_str().map(|k| format!(" ({k})")).unwrap_or_default();
- md.push_str(&format!("- `{}` **{}**{key}", s(c, "id"), s(c, "label")));
- let p = s(c, "params");
+ let label = command_text(c, "label").trim();
+ md.push_str(&format!("### {}\n\n", prose(if label.is_empty() { "Unnamed command" } else { label })));
+ let tab = command_text(c, "tab").trim();
+ let panel = command_text(c, "panel").trim();
+ if !tab.is_empty() {
+ let location = if panel.is_empty() { tab.to_string() } else { format!("{tab} › {panel}") };
+ md.push_str(&format!("**Command group:** {}\n\n", prose(&location)));
+ }
+ let shortcut = command_text(c, "shortcut").trim();
+ if !shortcut.is_empty() {
+ md.push_str(&format!("**Default keyboard shortcut:** {}\n\n", prose(shortcut)));
+ }
+ if let Some((label, path)) = guide(c) {
+ md.push_str(&format!("Read the [{label}]({path}).\n\n"));
+ }
+ md.push_str("<details>\n<summary>Automation details</summary>\n\n");
+ md.push_str(&format!("<p><strong>Command ID:</strong> <code>{}</code></p>\n\n", html(command_text(c, "id"))));
+ let p = command_text(c, "params");
if !p.is_empty() {
- md.push_str(&format!("<br>``{}``", p.replace('\n', " ")));
+ // HTML code blocks preserve the complete source text, including newlines and
+ // arbitrary runs of backticks, without letting it close the details element.
+ md.push_str(&format!(
+ "<p><strong>Parameters:</strong></p>\n<pre><code style=\"white-space: pre-wrap; overflow-wrap: anywhere;\">{}</code></pre>\n",
+ html(p)
+ ));
+ } else {
+ md.push_str("<p>No parameter description is provided by the command registry.</p>\n");
}
- md.push('\n');
+ md.push_str("\n</details>\n\n");
}
}
md
}
+fn command_text<'a>(command: &'a Value, key: &str) -> &'a str {
+ command.get(key).and_then(Value::as_str).unwrap_or_default()
+}
+
+/// Text in generated Markdown is literal text, never contributor-provided Markdown or HTML.
+fn prose(text: &str) -> String {
+ let mut escaped = String::new();
+ for ch in text.chars() {
+ match ch {
+ '\r' | '\n' => escaped.push(' '),
+ '\\' | '`' | '*' | '_' | '[' | ']' | '{' | '}' | '(' | ')' | '#' | '+' | '-' | '!' | '|' | '~' => {
+ escaped.push('\\');
+ escaped.push(ch);
+ }
+ _ => escaped.push(ch),
+ }
+ }
+ html(&escaped)
+}
+
+/// Escape once, including ampersands that already look like HTML entities.
+fn html(text: &str) -> String {
+ text.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;").replace('\'', "&#39;")
+}
+
+/// Only link to guide pages that exist; parameter descriptions are deliberately not parsed.
+fn guide(command: &Value) -> Option<(&'static str, &'static str)> {
+ let area = command_text(command, "id").split('.').next().unwrap_or_default();
+ match area {
+ "parameters" | "expr" | "config" => Some(("parameters and expressions guide", "../guide/parameters.md")),
+ "component" | "occurrence" | "joint" | "motion" => Some(("components and joints guide", "../guide/assemblies.md")),
+ "file" | "doc" => Some(("import and export guide", "../guide/files.md")),
+ "view" | "browser" | "select" => Some(("window tour", "../guide/ui-tour.md")),
+ _ => match command_text(command, "tab") {
+ "SKETCH" => Some(("sketching and constraints guide", "../guide/sketching.md")),
+ "SOLID" | "SURFACE" => Some(("solid features guide", "../guide/features.md")),
+ "SHEET METAL" => Some(("sheet metal guide", "../guide/sheet-metal.md")),
+ "PLASTIC" => Some(("plastic parts guide", "../guide/plastic.md")),
+ _ => None,
+ },
+ }
+}
+
fn add<'a>(sections: &mut Vec<(String, Vec<&'a Value>)>, title: String, c: &'a Value) {
match sections.iter_mut().find(|(t, _)| *t == title) {
Some((_, v)) => v.push(c),
None => sections.push((title, vec![c])),
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ fn decoded_code(text: &str) -> String {
+ text.replace("&lt;", "<").replace("&gt;", ">").replace("&quot;", "\"").replace("&#39;", "'").replace("&amp;", "&")
+ }
+
+ #[test]
+ fn every_command_has_one_entry_with_its_complete_automation_details() {
+ let cmds = [
+ json!({"id":"file.export","label":"Export","params":"path: text","tab":"","panel":""}),
+ json!({"id":"solid.extrude","label":"Extrude","params":"distance: expr","tab":"SOLID","panel":"CREATE","shortcut":"E"}),
+ json!({"id":"sketch.line","label":"Line","params":"points: [x,y]","tab":"SKETCH","panel":"CREATE"}),
+ json!({"id":"future.action","label":"Future action","params":"option?: text","tab":"NEW WORKSPACE","panel":"TOOLS"}),
+ ];
+ let md = reference(&cmds);
+ let ids: Vec<&str> = md.split("<strong>Command ID:</strong> <code>").skip(1).map(|tail| tail.split("</code>").next().unwrap()).collect();
+ assert_eq!(ids, ["solid.extrude", "sketch.line", "file.export", "future.action"]);
+ assert_eq!(md.matches("<details>").count(), cmds.len());
+ assert_eq!(md.matches("### ").count(), cmds.len());
+ assert!(md.contains("### Extrude\n\n**Command group:** SOLID › CREATE\n\n**Default keyboard shortcut:** E"));
+ assert!(md.contains("## Other commands: future"));
+ assert!(md.contains("**Command group:** NEW WORKSPACE › TOOLS"));
+ for cmd in &cmds {
+ assert!(md.contains(&format!(
+ "<pre><code style=\"white-space: pre-wrap; overflow-wrap: anywhere;\">{}</code></pre>",
+ command_text(cmd, "params")
+ )));
+ }
+ }
+
+ #[test]
+ fn source_markup_cannot_add_links_headings_or_close_automation_details() {
+ let params = "path: id|name\n```html\n</code></pre></details><script>alert('x')</script>\n``````\n&amper; &lt; \n";
+ let md = reference(&[json!({
+ "id":"odd.<tag>&id",
+ "label":"[Follow](javascript:alert(1)) <img src=x>\n### Injected",
+ "tab":"UNKNOWN <script>",
+ "panel":"[Panel](https://invalid.example)",
+ "shortcut":"Ctrl+<b>&`",
+ "params":params
+ })]);
+ assert_eq!(md.matches("<details>").count(), 1);
+ assert_eq!(md.matches("</details>").count(), 1);
+ assert_eq!(md.lines().filter(|line| line.starts_with("### ")).count(), 1);
+ assert!(!md.contains("<script>"));
+ assert!(!md.contains("<img"));
+ assert!(!md.contains("[Follow]("));
+ assert!(!md.contains("[Panel]("));
+ let stored =
+ md.split("<pre><code style=\"white-space: pre-wrap; overflow-wrap: anywhere;\">").nth(1).unwrap().split("</code></pre>").next().unwrap();
+ assert_eq!(decoded_code(stored), params, "every parameter byte, including newlines and backticks, stays readable");
+ assert!(md.contains("<code>odd.&lt;tag&gt;&amp;id</code>"));
+ }
+
+ #[test]
+ fn missing_optional_metadata_does_not_invent_a_toolbar_shortcut_or_guide() {
+ for cmd in [
+ json!({"id":"future.unlisted","label":"Unlisted"}),
+ json!({"id":"future.unlisted","label":"Unlisted","tab":false,"panel":42,"shortcut":false,"params":null}),
+ json!({"id":"future.unlisted","label":"Unlisted","tab":" ","panel":" ","shortcut":" \n"}),
+ ] {
+ let md = reference(&[cmd]);
+ assert!(md.contains("### Unlisted"));
+ assert!(md.contains("<code>future.unlisted</code>"));
+ assert!(!md.contains("**Command group:**"));
+ assert!(!md.contains("**Default keyboard shortcut:**"));
+ assert!(!md.contains("Read the ["));
+ assert!(md.contains("No parameter description is provided"));
+ }
+ }
+
+ #[test]
+ fn related_guides_are_existing_pages_and_cover_commands_without_a_toolbar() {
+ let samples = [
+ json!({"id":"parameters.change"}),
+ json!({"id":"joint.drive"}),
+ json!({"id":"file.export"}),
+ json!({"id":"view.home"}),
+ json!({"id":"sketch.line","tab":"SKETCH"}),
+ json!({"id":"solid.extrude","tab":"SOLID"}),
+ json!({"id":"surface.patch","tab":"SURFACE"}),
+ json!({"id":"sheet.flange","tab":"SHEET METAL"}),
+ json!({"id":"plastic.boss","tab":"PLASTIC"}),
+ ];
+ let base = Path::new(env!("CARGO_MANIFEST_DIR")).join("../docs/book/src/reference");
+ for cmd in samples {
+ let (label, path) = guide(&cmd).expect("a related user guide");
+ assert!(base.join(path).is_file(), "missing guide {path}");
+ assert!(reference(&[cmd]).contains(&format!("Read the [{label}]({path}).")));
+ }
+ assert!(guide(&json!({"id":"future.unlisted","tab":"NEW WORKSPACE"})).is_none());
+ }
+}