From 199c9c2cfbafea1caf279597660660abbd0dacca Mon Sep 17 00:00:00 2001 From: mattwparas Date: Mon, 12 Aug 2024 17:02:14 -0700 Subject: [PATCH] add partial documentation generation --- Cargo.lock | 17 ++++-- helix-term/Cargo.toml | 1 + helix-term/src/commands/engine/steel.rs | 80 ++++++++++++++++++++----- xtask/src/main.rs | 2 + 4 files changed, 82 insertions(+), 18 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index c5ba5a8a7..df1150b19 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1606,6 +1606,7 @@ dependencies = [ "signal-hook-tokio", "smallvec", "steel-core", + "steel-doc", "tempfile", "termini", "thiserror", @@ -2636,7 +2637,7 @@ checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" [[package]] name = "steel-core" version = "0.6.0" -source = "git+https://github.com/mattwparas/steel.git#9e84aa69fd145fe91bc314319db41e41a8d379e8" +source = "git+https://github.com/mattwparas/steel.git#d31238b17b28db5cca34d92d5c1217d51e91ab82" dependencies = [ "abi_stable", "anyhow", @@ -2676,17 +2677,25 @@ dependencies = [ [[package]] name = "steel-derive" version = "0.5.0" -source = "git+https://github.com/mattwparas/steel.git#9e84aa69fd145fe91bc314319db41e41a8d379e8" +source = "git+https://github.com/mattwparas/steel.git#d31238b17b28db5cca34d92d5c1217d51e91ab82" dependencies = [ "proc-macro2", "quote", "syn 2.0.71", ] +[[package]] +name = "steel-doc" +version = "0.6.0" +source = "git+https://github.com/mattwparas/steel.git#d31238b17b28db5cca34d92d5c1217d51e91ab82" +dependencies = [ + "steel-core", +] + [[package]] name = "steel-gen" version = "0.2.0" -source = "git+https://github.com/mattwparas/steel.git#9e84aa69fd145fe91bc314319db41e41a8d379e8" +source = "git+https://github.com/mattwparas/steel.git#d31238b17b28db5cca34d92d5c1217d51e91ab82" dependencies = [ "codegen", "serde", @@ -2696,7 +2705,7 @@ dependencies = [ [[package]] name = "steel-parser" version = "0.6.0" -source = "git+https://github.com/mattwparas/steel.git#9e84aa69fd145fe91bc314319db41e41a8d379e8" +source = "git+https://github.com/mattwparas/steel.git#d31238b17b28db5cca34d92d5c1217d51e91ab82" dependencies = [ "fxhash", "lasso", diff --git a/helix-term/Cargo.toml b/helix-term/Cargo.toml index 24806de36..1a379316f 100644 --- a/helix-term/Cargo.toml +++ b/helix-term/Cargo.toml @@ -75,6 +75,7 @@ grep-searcher = "0.1.13" # plugin support steel-core = { workspace = true, optional = true } +steel-doc = { git = "https://github.com/mattwparas/steel.git", version = "0.6.0" } [target.'cfg(not(windows))'.dependencies] # https://github.com/vorner/signal-hook/issues/100 signal-hook-tokio = { version = "0.3", features = ["futures-v0_3"] } diff --git a/helix-term/src/commands/engine/steel.rs b/helix-term/src/commands/engine/steel.rs index 804a8b50b..70a071891 100644 --- a/helix-term/src/commands/engine/steel.rs +++ b/helix-term/src/commands/engine/steel.rs @@ -8,7 +8,6 @@ use helix_core::{ Range, Selection, Tendril, }; use helix_event::register_hook; -use helix_stdx::path::expand_tilde; use helix_view::{ annotations::diagnostics::DiagnosticFilter, document::Mode, @@ -177,31 +176,59 @@ fn load_static_commands(engine: &mut Engine, generate_sources: bool) { // Register everything in the static command list as well // These just accept the context, no arguments for command in MappableCommand::STATIC_COMMAND_LIST { - if let MappableCommand::Static { name, fun, .. } = command { + if let MappableCommand::Static { name, fun, doc } = command { module.register_fn(name, fun); if generate_sources { + let mut docstring = doc + .lines() + .map(|x| { + let mut line = ";;".to_string(); + line.push_str(x); + line.push_str("\n"); + line + }) + .collect::(); + + docstring.pop(); + builtin_static_command_module.push_str(&format!( r#" (provide {}) +;;@doc +{} (define ({}) (helix.static.{} *helix.cx*)) "#, - name, name, name + name, docstring, name, name )); } } } - let mut template_function_arity_1 = |name: &str| { + let mut template_function_arity_1 = |name: &str, doc: &str| { if generate_sources { + let mut docstring = doc + .lines() + .map(|x| { + let mut line = ";;".to_string(); + line.push_str(x); + line.push_str("\n"); + line + }) + .collect::(); + + docstring.pop(); + builtin_static_command_module.push_str(&format!( r#" (provide {}) +;;@doc +{} (define ({} arg) (helix.static.{} *helix.cx* arg)) "#, - name, name, name + name, docstring, name, name )); } }; @@ -209,22 +236,40 @@ fn load_static_commands(engine: &mut Engine, generate_sources: bool) { // Adhoc static commands that probably needs evaluating // Arity 1 module.register_fn("insert_char", insert_char); - template_function_arity_1("insert_char"); + template_function_arity_1( + "insert_char", + "Insert a given character at the cursor cursor position", + ); module.register_fn("insert_string", insert_string); - template_function_arity_1("insert_string"); + template_function_arity_1( + "insert_string", + "Insert a given string at the current cursor position", + ); module.register_fn("set-current-selection-object!", set_selection); - template_function_arity_1("set-current-selection-object!"); + template_function_arity_1( + "set-current-selection-object!", + "Update the selection object to the current selection within the editor", + ); - // module.register_fn("search-in-directory", search_in_directory); // template_function_arity_1("search-in-directory"); module.register_fn("regex-selection", regex_selection); - template_function_arity_1("regex-selection"); + template_function_arity_1( + "regex-selection", + "Run the given regex within the existing buffer", + ); module.register_fn("replace-selection-with", replace_selection); - template_function_arity_1("replace-selection-with"); + template_function_arity_1( + "replace-selection-with", + "Replace the existing selection with the given string", + ); module.register_fn("cx->current-file", current_path); - template_function_arity_1("cx->current-file"); + template_function_arity_1("cx->current-file", "Get the currently focused file path"); module.register_fn("enqueue-expression-in-engine", run_expression_in_engine); - template_function_arity_1("enqueue-expression-in-engine"); + template_function_arity_1( + "enqueue-expression-in-engine", + "Enqueue an expression to run at the top level context, + after the existing function context has exited.", + ); let mut template_function_arity_0 = |name: &str| { if generate_sources { @@ -998,6 +1043,13 @@ impl super::PluginSystem for SteelScriptingEngine { // Generate sources directly with a fresh engine let mut engine = Engine::new(); configure_builtin_sources(&mut engine, true); + // Generate documentation as well + let target = helix_runtime_search_path(); + + let mut writer = std::io::BufWriter::new(std::fs::File::create("steel-docs.md").unwrap()); + + // Generate markdown docs + steel_doc::walk_dir(&mut writer, target, &mut engine).unwrap(); } } @@ -1912,7 +1964,7 @@ fn load_misc_api(engine: &mut Engine, generate_sources: bool) { engine.register_module(module); } -fn helix_runtime_search_path() -> PathBuf { +pub fn helix_runtime_search_path() -> PathBuf { helix_loader::config_dir().join("helix") } diff --git a/xtask/src/main.rs b/xtask/src/main.rs index d71343f8c..6e4ff1237 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -102,6 +102,8 @@ Usage: Run with `cargo xtask `, eg. `cargo xtask docgen`. Tasks: docgen: Generate files to be included in the mdbook output. query-check: Check that tree-sitter queries are valid. + code-gen: Generate files associated with steel + steel: Install steel " ); }