From 1f7f8e5104dd2d8019ce3ded191ac8999f45ac93 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 10:49:50 -0400 Subject: [PATCH] docs: update api docs, make others show up on site --- api.go | 32 +++++++++++++++++++++++----- docs/api/_index.md | 2 +- docs/api/hilbish/_index.md | 43 ++++++++++++++++++++++++++++++++------ docs/completions.md | 9 ++++++++ docs/jobs.md | 9 ++++++++ docs/lunacolors.md | 7 +++++++ docs/nature/_index.md | 7 +++++++ docs/vim-mode/_index.md | 7 +++++++ docs/vim-mode/actions.md | 9 ++++++++ emmyLuaDocs/hilbish.lua | 11 +++++----- 10 files changed, 119 insertions(+), 17 deletions(-) diff --git a/api.go b/api.go index b7afb3d..71a4b7b 100644 --- a/api.go +++ b/api.go @@ -336,9 +336,19 @@ func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // alias(cmd, orig) -// Sets an alias of `cmd` to `orig` -// --- @param cmd string -// --- @param orig string +// Sets an alias, with a name of `cmd` to another command. +// #param cmd string Name of the alias +// #param orig string Command that will be aliased +/* +#example +-- With this, "ga file" will turn into "git add file" +hilbish.alias('ga', 'git add') + +-- Numbered substitutions are supported here! +hilbish.alias('dircount', 'ls %1 | wc -l') +-- "dircount ~" would count how many files are in ~ (home directory). +#example +*/ func hlalias(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(2); err != nil { return nil, err @@ -358,8 +368,20 @@ func hlalias(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // appendPath(dir) -// Appends `dir` to $PATH -// --- @param dir string|table +// Appends the provided dir to the command path (`$PATH`) +// #param dir string|table Directory (or directories) to append to path +/* +#example +hilbish.appendPath '~/go/bin' +-- Will add ~/go/bin to the command path. + +-- Or do multiple: +hilbush.appendPath { + '~/go/bin', + '~/.local/bin' +} +#example +*/ func hlappendPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err diff --git a/docs/api/_index.md b/docs/api/_index.md index 8c9f722..f34539e 100644 --- a/docs/api/_index.md +++ b/docs/api/_index.md @@ -1,7 +1,7 @@ --- title: API layout: doc -weight: -50 +weight: -100 menu: docs --- diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 8278376..8eded6b 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -14,8 +14,8 @@ interfaces and functions which directly relate to shell functionality. ## Functions ||| |----|----| -|alias(cmd, orig)|Sets an alias of `cmd` to `orig`| -|appendPath(dir)|Appends `dir` to $PATH| +|alias(cmd, orig)|Sets an alias, with a name of `cmd` to another command.| +|appendPath(dir)|Appends the provided dir to the command path (`$PATH`)| |complete(scope, cb)|Registers a completion handler for `scope`.| |cwd() -> string|Returns the current directory of the shell| |exec(cmd)|Replaces running hilbish with `cmd`| @@ -54,9 +54,25 @@ hilbish.alias(cmd, orig) -Sets an alias of `cmd` to `orig` +Sets an alias, with a name of `cmd` to another command. + + #### Parameters -This function has no parameters. +`string` **`cmd`** +Name of the alias + +`string` **`orig`** +Command that will be aliased + +#### Example +```lua +-- With this, "ga file" will turn into "git add file" +hilbish.alias('ga', 'git add') + +-- Numbered substitutions are supported here! +hilbish.alias('dircount', 'ls %1 | wc -l') +-- "dircount ~" would count how many files are in ~ (home directory). +````
@@ -67,9 +83,24 @@ hilbish.appendPath(dir) -Appends `dir` to $PATH +Appends the provided dir to the command path (`$PATH`) + + #### Parameters -This function has no parameters. +`string|table` **`dir`** +Directory (or directories) to append to path + +#### Example +```lua +hilbish.appendPath '~/go/bin' +-- Will add ~/go/bin to the command path. + +-- Or do multiple: +hilbush.appendPath { + '~/go/bin', + '~/.local/bin' +} +````
diff --git a/docs/completions.md b/docs/completions.md index c2de27a..0ea60c2 100644 --- a/docs/completions.md +++ b/docs/completions.md @@ -1,3 +1,12 @@ +--- +title: Completions +description: Tab completion for commands. +layout: doc +menu: + docs: + parent: "Features" +--- + Hilbish has a pretty good completion system. It has a nice looking menu, with 2 types of menus: grid (like file completions) or list. diff --git a/docs/jobs.md b/docs/jobs.md index a5fee9c..59f2113 100644 --- a/docs/jobs.md +++ b/docs/jobs.md @@ -1,3 +1,12 @@ +--- +title: Jobs +description: Controls for background commands in Hilbish. +layout: doc +menu: + docs: + parent: "Features" +--- + Hilbish has pretty standard job control. It's missing one or two things, but works well. One thing which is different from other shells (besides Hilbish) itself is the API for jobs, and of course it's in Lua. diff --git a/docs/lunacolors.md b/docs/lunacolors.md index e122fef..bde809c 100644 --- a/docs/lunacolors.md +++ b/docs/lunacolors.md @@ -1,3 +1,10 @@ +--- +title: Lunacolors +layout: doc +weight: -60 +menu: docs +--- + Lunacolors is an ANSI color/styling library for Lua. It is included by default in standard Hilbish distributions to provide easy styling for things like prompts and text. diff --git a/docs/nature/_index.md b/docs/nature/_index.md index 53df6ca..460d6a3 100644 --- a/docs/nature/_index.md +++ b/docs/nature/_index.md @@ -1,3 +1,10 @@ +--- +title: Nature +layout: doc +weight: -90 +menu: docs +--- + A bit after creation, we have the outside nature. Little plants, seeds, growing to their final phase: a full plant. A lot of Hilbish itself is written in Go, but there are parts made in Lua, being most builtins diff --git a/docs/vim-mode/_index.md b/docs/vim-mode/_index.md index a30fe74..bda01e9 100644 --- a/docs/vim-mode/_index.md +++ b/docs/vim-mode/_index.md @@ -1,3 +1,10 @@ +--- +title: Vim Mode +layout: doc +weight: -90 +menu: docs +--- + Hilbish has a Vim binding input mode accessible for use. It can be enabled with the `hilbish.inputMode` function (check `doc hilbish`). diff --git a/docs/vim-mode/actions.md b/docs/vim-mode/actions.md index 9dfb7b2..9757827 100644 --- a/docs/vim-mode/actions.md +++ b/docs/vim-mode/actions.md @@ -1,3 +1,12 @@ +--- +title: Actions +layout: doc +weight: -80 +menu: + docs: + parent: "Vim Mode" +--- + Vim actions are essentially just when a user uses a Vim keybind. Things like yanking and pasting are Vim actions. This is not an "offical Vim thing," just a Hilbish thing. diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index 2ee93ed..ea30efd 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -49,13 +49,14 @@ function hilbish.editor.getChar() end --- @param text string function hilbish.editor.setVimRegister(register, text) end ---- Sets an alias of `cmd` to `orig` ---- @param cmd string ---- @param orig string +--- Sets an alias, with a name of `cmd` to another command. +--- +--- function hilbish.alias(cmd, orig) end ---- Appends `dir` to $PATH ---- @param dir string|table +--- Appends the provided dir to the command path (`$PATH`) +--- +--- function hilbish.appendPath(dir) end --- Registers a completion handler for `scope`.