aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGokul Soumya2021-11-17 13:30:11 +0000
committerBlaž Hrastnik2021-12-08 01:23:50 +0000
commit71292f9f11bd2b50568efd111239f693be26a36a (patch)
treec34eedcc0c00a527708650a0da9853a6cfd22911
parent9bdbafa0759e482d628b7e1940809963c556ec95 (diff)
docs: Auto generate command list
-rw-r--r--.cargo/config2
-rw-r--r--Cargo.lock7
-rw-r--r--Cargo.toml1
-rw-r--r--README.md16
-rw-r--r--book/src/SUMMARY.md3
-rw-r--r--book/src/commands.md5
-rw-r--r--book/src/generated/typable-cmd.md43
-rw-r--r--docs/CONTRIBUTING.md37
-rw-r--r--helix-term/src/commands.rs8
-rw-r--r--xtask/Cargo.toml9
-rw-r--r--xtask/src/main.rs86
11 files changed, 197 insertions, 20 deletions
diff --git a/.cargo/config b/.cargo/config
new file mode 100644
index 00000000..35049cbc
--- /dev/null
+++ b/.cargo/config
@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --package xtask --"
diff --git a/Cargo.lock b/Cargo.lock
index 47a6c01e..b3032465 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1259,3 +1259,10 @@ name = "winapi-x86_64-pc-windows-gnu"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "xtask"
+version = "0.5.0"
+dependencies = [
+ "helix-term",
+]
diff --git a/Cargo.toml b/Cargo.toml
index 580cccd6..8c3ee671 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -6,6 +6,7 @@ members = [
"helix-tui",
"helix-syntax",
"helix-lsp",
+ "xtask",
]
# Build helix-syntax in release mode to make the code path faster in development.
diff --git a/README.md b/README.md
index 3f4087b9..f651e30c 100644
--- a/README.md
+++ b/README.md
@@ -65,21 +65,7 @@ brew install helix
# Contributing
-Contributors are very welcome! **No contribution is too small and all contributions are valued.**
-
-Some suggestions to get started:
-
-- You can look at the [good first issue](https://github.com/helix-editor/helix/issues?q=is%3Aopen+label%3AE-easy+label%3AE-good-first-issue) label on the issue tracker.
-- Help with packaging on various distributions needed!
-- To use print debugging to the [Helix log file](https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file), you must:
- * Print using `log::info!`, `warn!`, or `error!`. (`log::info!("helix!")`)
- * Pass the appropriate verbosity level option for the desired log level. (`hx -v <file>` for info, more `v`s for higher severity inclusive)
-- If your preferred language is missing, integrating a tree-sitter grammar for
- it and defining syntax highlight queries for it is straight forward and
- doesn't require much knowledge of the internals.
-
-We provide an [architecture.md](./docs/architecture.md) that should give you
-a good overview of the internals.
+Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).
# Getting help
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 8cadb663..4da79925 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -2,10 +2,11 @@
- [Installation](./install.md)
- [Usage](./usage.md)
+ - [Keymap](./keymap.md)
+ - [Commands](./commands.md)
- [Migrating from Vim](./from-vim.md)
- [Configuration](./configuration.md)
- [Themes](./themes.md)
- - [Keymap](./keymap.md)
- [Key Remapping](./remapping.md)
- [Hooks](./hooks.md)
- [Languages](./languages.md)
diff --git a/book/src/commands.md b/book/src/commands.md
new file mode 100644
index 00000000..4c4a5c05
--- /dev/null
+++ b/book/src/commands.md
@@ -0,0 +1,5 @@
+# Commands
+
+Command mode can be activated by pressing `:`, similar to vim. Built-in commands:
+
+{{#include ./generated/typable-cmd.md}}
diff --git a/book/src/generated/typable-cmd.md b/book/src/generated/typable-cmd.md
new file mode 100644
index 00000000..5de5c787
--- /dev/null
+++ b/book/src/generated/typable-cmd.md
@@ -0,0 +1,43 @@
+| Name | Description |
+| --- | --- |
+| `:quit`, `:q` | Close the current view. |
+| `:quit!`, `:q!` | Close the current view forcefully (ignoring unsaved changes). |
+| `:open`, `:o` | Open a file from disk into the current view. |
+| `:buffer-close`, `:bc`, `:bclose` | Close the current buffer. |
+| `:buffer-close!`, `:bc!`, `:bclose!` | Close the current buffer forcefully (ignoring unsaved changes). |
+| `:write`, `:w` | Write changes to disk. Accepts an optional path (:write some/path.txt) |
+| `:new`, `:n` | Create a new scratch buffer. |
+| `:format`, `:fmt` | Format the file using the LSP formatter. |
+| `:indent-style` | Set the indentation style for editing. ('t' for tabs or 1-8 for number of spaces.) |
+| `:line-ending` | Set the document's default line ending. Options: crlf, lf, cr, ff, nel. |
+| `:earlier`, `:ear` | Jump back to an earlier point in edit history. Accepts a number of steps or a time span. |
+| `:later`, `:lat` | Jump to a later point in edit history. Accepts a number of steps or a time span. |
+| `:write-quit`, `:wq`, `:x` | Write changes to disk and close the current view. Accepts an optional path (:wq some/path.txt) |
+| `:write-quit!`, `:wq!`, `:x!` | Write changes to disk and close the current view forcefully. Accepts an optional path (:wq! some/path.txt) |
+| `:write-all`, `:wa` | Write changes from all views to disk. |
+| `:write-quit-all`, `:wqa`, `:xa` | Write changes from all views to disk and close all views. |
+| `:write-quit-all!`, `:wqa!`, `:xa!` | Write changes from all views to disk and close all views forcefully (ignoring unsaved changes). |
+| `:quit-all`, `:qa` | Close all views. |
+| `:quit-all!`, `:qa!` | Close all views forcefully (ignoring unsaved changes). |
+| `:cquit`, `:cq` | Quit with exit code (default 1). Accepts an optional integer exit code (:cq 2). |
+| `:theme` | Change the editor theme. |
+| `:clipboard-yank` | Yank main selection into system clipboard. |
+| `:clipboard-yank-join` | Yank joined selections into system clipboard. A separator can be provided as first argument. Default value is newline. |
+| `:primary-clipboard-yank` | Yank main selection into system primary clipboard. |
+| `:primary-clipboard-yank-join` | Yank joined selections into system primary clipboard. A separator can be provided as first argument. Default value is newline. |
+| `:clipboard-paste-after` | Paste system clipboard after selections. |
+| `:clipboard-paste-before` | Paste system clipboard before selections. |
+| `:clipboard-paste-replace` | Replace selections with content of system clipboard. |
+| `:primary-clipboard-paste-after` | Paste primary clipboard after selections. |
+| `:primary-clipboard-paste-before` | Paste primary clipboard before selections. |
+| `:primary-clipboard-paste-replace` | Replace selections with content of system primary clipboard. |
+| `:show-clipboard-provider` | Show clipboard provider name in status bar. |
+| `:change-current-directory`, `:cd` | Change the current working directory. |
+| `:show-directory`, `:pwd` | Show the current working directory. |
+| `:encoding` | Set encoding based on `https://encoding.spec.whatwg.org` |
+| `:reload` | Discard changes and reload from the source file. |
+| `:tree-sitter-scopes` | Display tree sitter scopes, primarily for theming and development. |
+| `:vsplit`, `:vs` | Open the file in a vertical split. |
+| `:hsplit`, `:hs`, `:sp` | Open the file in a horizontal split. |
+| `:tutor` | Open the tutorial. |
+| `:goto`, `:g` | Go to line number. |
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 00000000..7b923db8
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+# Contributing
+
+Contributors are very welcome! **No contribution is too small and all contributions are valued.**
+
+Some suggestions to get started:
+
+- You can look at the [good first issue][good-first-issue] label on the issue tracker.
+- Help with packaging on various distributions needed!
+- To use print debugging to the [Helix log file][log-file], you must:
+ * Print using `log::info!`, `warn!`, or `error!`. (`log::info!("helix!")`)
+ * Pass the appropriate verbosity level option for the desired log level. (`hx -v <file>` for info, more `v`s for higher severity inclusive)
+- If your preferred language is missing, integrating a tree-sitter grammar for
+ it and defining syntax highlight queries for it is straight forward and
+ doesn't require much knowledge of the internals.
+
+We provide an [architecture.md][architecture.md] that should give you
+a good overview of the internals.
+
+# Auto generated documentation
+
+Some parts of [the book][docs] are autogenerated from the code itself,
+like the list of `:commands` and supported languages. To generate these
+files, run
+
+```shell
+cargo xtask bookgen
+```
+
+inside the project. We use [xtask][xtask] as an ad-hoc task runner and
+thus do not require any dependencies other than `cargo` (You don't have
+to `cargo install` anything either).
+
+[good-first-issue]: https://github.com/helix-editor/helix/labels/E-easy
+[log-file]: https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file
+[architecture.md]: ./architecture.md
+[docs]: https://docs.helix-editor.com/
+[xtask]: https://github.com/matklad/cargo-xtask
diff --git a/helix-term/src/commands.rs b/helix-term/src/commands.rs
index 3e7ce712..4910790a 100644
--- a/helix-term/src/commands.rs
+++ b/helix-term/src/commands.rs
@@ -1949,7 +1949,7 @@ fn append_mode(cx: &mut Context) {
doc.set_selection(view.id, selection);
}
-mod cmd {
+pub mod cmd {
use super::*;
use std::collections::HashMap;
@@ -2679,7 +2679,7 @@ mod cmd {
TypableCommand {
name: "format",
aliases: &["fmt"],
- doc: "Format the file using a formatter.",
+ doc: "Format the file using the LSP formatter.",
fun: format,
completer: None,
},
@@ -2770,7 +2770,7 @@ mod cmd {
TypableCommand {
name: "theme",
aliases: &[],
- doc: "Change the theme of current view. Requires theme name as argument (:theme <name>)",
+ doc: "Change the editor theme.",
fun: theme,
completer: Some(completers::theme),
},
@@ -2854,7 +2854,7 @@ mod cmd {
TypableCommand {
name: "change-current-directory",
aliases: &["cd"],
- doc: "Change the current working directory (:cd <dir>).",
+ doc: "Change the current working directory.",
fun: change_current_directory,
completer: Some(completers::directory),
},
diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml
new file mode 100644
index 00000000..cb890de9
--- /dev/null
+++ b/xtask/Cargo.toml
@@ -0,0 +1,9 @@
+[package]
+name = "xtask"
+version = "0.5.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+helix-term = { version = "0.5", path = "../helix-term" }
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
new file mode 100644
index 00000000..4bf0ae9f
--- /dev/null
+++ b/xtask/src/main.rs
@@ -0,0 +1,86 @@
+use std::env;
+
+pub mod md_gen {
+ use super::path;
+ use std::fs;
+
+ use helix_term::commands::cmd::TYPABLE_COMMAND_LIST;
+
+ pub const TYPABLE_COMMANDS_MD_OUTPUT: &str = "typable-cmd.md";
+
+ pub fn typable_commands() -> String {
+ let mut md = String::new();
+ md.push_str("| Name | Description |\n");
+ md.push_str("| --- | --- |\n");
+
+ let cmdify = |s: &str| format!("`:{}`", s);
+
+ for cmd in TYPABLE_COMMAND_LIST {
+ let names = std::iter::once(&cmd.name)
+ .chain(cmd.aliases.iter())
+ .map(|a| cmdify(a))
+ .collect::<Vec<_>>()
+ .join(", ");
+
+ let entry = format!("| {} | {} |\n", names, cmd.doc);
+ md.push_str(&entry);
+ }
+
+ md
+ }
+
+ pub fn write(filename: &str, data: &str) {
+ let error = format!("Could not write to {}", filename);
+ let path = path::book_gen().join(filename);
+ fs::write(path, data).expect(&error);
+ }
+}
+
+pub mod path {
+ use std::path::{Path, PathBuf};
+
+ pub fn project_root() -> PathBuf {
+ Path::new(env!("CARGO_MANIFEST_DIR"))
+ .parent()
+ .unwrap()
+ .to_path_buf()
+ }
+
+ pub fn book_gen() -> PathBuf {
+ project_root().join("book/src/generated/")
+ }
+}
+
+pub mod tasks {
+ use super::md_gen;
+
+ pub fn bookgen() {
+ md_gen::write(
+ md_gen::TYPABLE_COMMANDS_MD_OUTPUT,
+ &md_gen::typable_commands(),
+ );
+ }
+
+ pub fn print_help() {
+ println!(
+ "
+Usage: Run with `cargo xtask <task>`, eg. `cargo xtask bookgen`.
+
+ Tasks:
+ bookgen: Generate files to be included in the mdbook output.
+"
+ );
+ }
+}
+
+fn main() -> Result<(), String> {
+ let task = env::args().nth(1);
+ match task {
+ None => tasks::print_help(),
+ Some(t) => match t.as_str() {
+ "bookgen" => tasks::bookgen(),
+ invalid => return Err(format!("Invalid task name: {}", invalid)),
+ },
+ };
+ Ok(())
+}