git.iko.soy/helix
on master help sign in
docs: Auto generate command list
commit71292f9f11bd2b50568efd111239f693be26a36a authorGokul Soumya <gokulps15@gmail.com> dateWed 17 Nov 2021, 19:00 (5 years ago) parent9bdbafa
11 files changed+197−20
compare with master
unifiedsplit
.cargo/config+2 Cargo.lock+7 Cargo.toml+1 README.md+1−15 book/src/SUMMARY.md+2−1 book/src/commands.md+5 book/src/generated/typable-cmd.md+43 docs/CONTRIBUTING.md+37 helix-term/src/commands.rs+4−4 xtask/Cargo.toml+9 xtask/src/main.rs+86
.cargo/confignew file+2
@@ -0,0 +1,2 @@
1+[alias]
2+xtask = "run --package xtask --"
Cargo.lock+7
@@ -1259,3 +1259,10 @@ name = "winapi-x86_64-pc-windows-gnu"
12591259version = "0.4.0"
12601260source = "registry+https://github.com/rust-lang/crates.io-index"
12611261checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
1262+
1263+[[package]]
1264+name = "xtask"
1265+version = "0.5.0"
1266+dependencies = [
1267+ "helix-term",
1268+]
Cargo.toml+1
@@ -6,6 +6,7 @@ members = [
66 "helix-tui",
77 "helix-syntax",
88 "helix-lsp",
9+ "xtask",
910]
1011
1112# Build helix-syntax in release mode to make the code path faster in development.
README.md+1−15
@@ -65,21 +65,7 @@ brew install helix
6565
6666# Contributing
6767
68−Contributors are very welcome! **No contribution is too small and all contributions are valued.**
69−
70−Some suggestions to get started:
71−
72−- 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.
73−- Help with packaging on various distributions needed!
74−- To use print debugging to the [Helix log file](https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file), you must:
75− * Print using `log::info!`, `warn!`, or `error!`. (`log::info!("helix!")`)
76− * Pass the appropriate verbosity level option for the desired log level. (`hx -v <file>` for info, more `v`s for higher severity inclusive)
77−- If your preferred language is missing, integrating a tree-sitter grammar for
78− it and defining syntax highlight queries for it is straight forward and
79− doesn't require much knowledge of the internals.
80−
81−We provide an [architecture.md](./docs/architecture.md) that should give you
82−a good overview of the internals.
68+Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).
8369
8470# Getting help
8571
book/src/SUMMARY.md+2−1
@@ -2,10 +2,11 @@
22
33- [Installation](./install.md)
44- [Usage](./usage.md)
5+ - [Keymap](./keymap.md)
6+ - [Commands](./commands.md)
57- [Migrating from Vim](./from-vim.md)
68- [Configuration](./configuration.md)
79 - [Themes](./themes.md)
8− - [Keymap](./keymap.md)
910 - [Key Remapping](./remapping.md)
1011 - [Hooks](./hooks.md)
1112 - [Languages](./languages.md)
book/src/commands.mdnew file+5
@@ -0,0 +1,5 @@
1+# Commands
2+
3+Command mode can be activated by pressing `:`, similar to vim. Built-in commands:
4+
5+{{#include ./generated/typable-cmd.md}}
book/src/generated/typable-cmd.mdnew file+43
@@ -0,0 +1,43 @@
1+| Name | Description |
2+| --- | --- |
3+| `:quit`, `:q` | Close the current view. |
4+| `:quit!`, `:q!` | Close the current view forcefully (ignoring unsaved changes). |
5+| `:open`, `:o` | Open a file from disk into the current view. |
6+| `:buffer-close`, `:bc`, `:bclose` | Close the current buffer. |
7+| `:buffer-close!`, `:bc!`, `:bclose!` | Close the current buffer forcefully (ignoring unsaved changes). |
8+| `:write`, `:w` | Write changes to disk. Accepts an optional path (:write some/path.txt) |
9+| `:new`, `:n` | Create a new scratch buffer. |
10+| `:format`, `:fmt` | Format the file using the LSP formatter. |
11+| `:indent-style` | Set the indentation style for editing. ('t' for tabs or 1-8 for number of spaces.) |
12+| `:line-ending` | Set the document's default line ending. Options: crlf, lf, cr, ff, nel. |
13+| `:earlier`, `:ear` | Jump back to an earlier point in edit history. Accepts a number of steps or a time span. |
14+| `:later`, `:lat` | Jump to a later point in edit history. Accepts a number of steps or a time span. |
15+| `:write-quit`, `:wq`, `:x` | Write changes to disk and close the current view. Accepts an optional path (:wq some/path.txt) |
16+| `:write-quit!`, `:wq!`, `:x!` | Write changes to disk and close the current view forcefully. Accepts an optional path (:wq! some/path.txt) |
17+| `:write-all`, `:wa` | Write changes from all views to disk. |
18+| `:write-quit-all`, `:wqa`, `:xa` | Write changes from all views to disk and close all views. |
19+| `:write-quit-all!`, `:wqa!`, `:xa!` | Write changes from all views to disk and close all views forcefully (ignoring unsaved changes). |
20+| `:quit-all`, `:qa` | Close all views. |
21+| `:quit-all!`, `:qa!` | Close all views forcefully (ignoring unsaved changes). |
22+| `:cquit`, `:cq` | Quit with exit code (default 1). Accepts an optional integer exit code (:cq 2). |
23+| `:theme` | Change the editor theme. |
24+| `:clipboard-yank` | Yank main selection into system clipboard. |
25+| `:clipboard-yank-join` | Yank joined selections into system clipboard. A separator can be provided as first argument. Default value is newline. |
26+| `:primary-clipboard-yank` | Yank main selection into system primary clipboard. |
27+| `:primary-clipboard-yank-join` | Yank joined selections into system primary clipboard. A separator can be provided as first argument. Default value is newline. |
28+| `:clipboard-paste-after` | Paste system clipboard after selections. |
29+| `:clipboard-paste-before` | Paste system clipboard before selections. |
30+| `:clipboard-paste-replace` | Replace selections with content of system clipboard. |
31+| `:primary-clipboard-paste-after` | Paste primary clipboard after selections. |
32+| `:primary-clipboard-paste-before` | Paste primary clipboard before selections. |
33+| `:primary-clipboard-paste-replace` | Replace selections with content of system primary clipboard. |
34+| `:show-clipboard-provider` | Show clipboard provider name in status bar. |
35+| `:change-current-directory`, `:cd` | Change the current working directory. |
36+| `:show-directory`, `:pwd` | Show the current working directory. |
37+| `:encoding` | Set encoding based on `https://encoding.spec.whatwg.org` |
38+| `:reload` | Discard changes and reload from the source file. |
39+| `:tree-sitter-scopes` | Display tree sitter scopes, primarily for theming and development. |
40+| `:vsplit`, `:vs` | Open the file in a vertical split. |
41+| `:hsplit`, `:hs`, `:sp` | Open the file in a horizontal split. |
42+| `:tutor` | Open the tutorial. |
43+| `:goto`, `:g` | Go to line number. |
docs/CONTRIBUTING.mdnew file+37
@@ -0,0 +1,37 @@
1+# Contributing
2+
3+Contributors are very welcome! **No contribution is too small and all contributions are valued.**
4+
5+Some suggestions to get started:
6+
7+- You can look at the [good first issue][good-first-issue] label on the issue tracker.
8+- Help with packaging on various distributions needed!
9+- To use print debugging to the [Helix log file][log-file], you must:
10+ * Print using `log::info!`, `warn!`, or `error!`. (`log::info!("helix!")`)
11+ * Pass the appropriate verbosity level option for the desired log level. (`hx -v <file>` for info, more `v`s for higher severity inclusive)
12+- If your preferred language is missing, integrating a tree-sitter grammar for
13+ it and defining syntax highlight queries for it is straight forward and
14+ doesn't require much knowledge of the internals.
15+
16+We provide an [architecture.md][architecture.md] that should give you
17+a good overview of the internals.
18+
19+# Auto generated documentation
20+
21+Some parts of [the book][docs] are autogenerated from the code itself,
22+like the list of `:commands` and supported languages. To generate these
23+files, run
24+
25+```shell
26+cargo xtask bookgen
27+```
28+
29+inside the project. We use [xtask][xtask] as an ad-hoc task runner and
30+thus do not require any dependencies other than `cargo` (You don't have
31+to `cargo install` anything either).
32+
33+[good-first-issue]: https://github.com/helix-editor/helix/labels/E-easy
34+[log-file]: https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file
35+[architecture.md]: ./architecture.md
36+[docs]: https://docs.helix-editor.com/
37+[xtask]: https://github.com/matklad/cargo-xtask
helix-term/src/commands.rs+4−4
@@ -1949,7 +1949,7 @@ fn append_mode(cx: &mut Context) {
19491949 doc.set_selection(view.id, selection);
19501950}
19511951
1952−mod cmd {
1952+pub mod cmd {
19531953 use super::*;
19541954 use std::collections::HashMap;
19551955
@@ -2679,7 +2679,7 @@ mod cmd {
26792679 TypableCommand {
26802680 name: "format",
26812681 aliases: &["fmt"],
2682− doc: "Format the file using a formatter.",
2682+ doc: "Format the file using the LSP formatter.",
26832683 fun: format,
26842684 completer: None,
26852685 },
@@ -2770,7 +2770,7 @@ mod cmd {
27702770 TypableCommand {
27712771 name: "theme",
27722772 aliases: &[],
2773− doc: "Change the theme of current view. Requires theme name as argument (:theme <name>)",
2773+ doc: "Change the editor theme.",
27742774 fun: theme,
27752775 completer: Some(completers::theme),
27762776 },
@@ -2854,7 +2854,7 @@ mod cmd {
28542854 TypableCommand {
28552855 name: "change-current-directory",
28562856 aliases: &["cd"],
2857− doc: "Change the current working directory (:cd <dir>).",
2857+ doc: "Change the current working directory.",
28582858 fun: change_current_directory,
28592859 completer: Some(completers::directory),
28602860 },
xtask/Cargo.tomlnew file+9
@@ -0,0 +1,9 @@
1+[package]
2+name = "xtask"
3+version = "0.5.0"
4+edition = "2021"
5+
6+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
7+
8+[dependencies]
9+helix-term = { version = "0.5", path = "../helix-term" }
xtask/src/main.rsnew file+86
@@ -0,0 +1,86 @@
1+use std::env;
2+
3+pub mod md_gen {
4+ use super::path;
5+ use std::fs;
6+
7+ use helix_term::commands::cmd::TYPABLE_COMMAND_LIST;
8+
9+ pub const TYPABLE_COMMANDS_MD_OUTPUT: &str = "typable-cmd.md";
10+
11+ pub fn typable_commands() -> String {
12+ let mut md = String::new();
13+ md.push_str("| Name | Description |\n");
14+ md.push_str("| --- | --- |\n");
15+
16+ let cmdify = |s: &str| format!("`:{}`", s);
17+
18+ for cmd in TYPABLE_COMMAND_LIST {
19+ let names = std::iter::once(&cmd.name)
20+ .chain(cmd.aliases.iter())
21+ .map(|a| cmdify(a))
22+ .collect::<Vec<_>>()
23+ .join(", ");
24+
25+ let entry = format!("| {} | {} |\n", names, cmd.doc);
26+ md.push_str(&entry);
27+ }
28+
29+ md
30+ }
31+
32+ pub fn write(filename: &str, data: &str) {
33+ let error = format!("Could not write to {}", filename);
34+ let path = path::book_gen().join(filename);
35+ fs::write(path, data).expect(&error);
36+ }
37+}
38+
39+pub mod path {
40+ use std::path::{Path, PathBuf};
41+
42+ pub fn project_root() -> PathBuf {
43+ Path::new(env!("CARGO_MANIFEST_DIR"))
44+ .parent()
45+ .unwrap()
46+ .to_path_buf()
47+ }
48+
49+ pub fn book_gen() -> PathBuf {
50+ project_root().join("book/src/generated/")
51+ }
52+}
53+
54+pub mod tasks {
55+ use super::md_gen;
56+
57+ pub fn bookgen() {
58+ md_gen::write(
59+ md_gen::TYPABLE_COMMANDS_MD_OUTPUT,
60+ &md_gen::typable_commands(),
61+ );
62+ }
63+
64+ pub fn print_help() {
65+ println!(
66+ "
67+Usage: Run with `cargo xtask <task>`, eg. `cargo xtask bookgen`.
68+
69+ Tasks:
70+ bookgen: Generate files to be included in the mdbook output.
71+"
72+ );
73+ }
74+}
75+
76+fn main() -> Result<(), String> {
77+ let task = env::args().nth(1);
78+ match task {
79+ None => tasks::print_help(),
80+ Some(t) => match t.as_str() {
81+ "bookgen" => tasks::bookgen(),
82+ invalid => return Err(format!("Invalid task name: {}", invalid)),
83+ },
84+ };
85+ Ok(())
86+}