From 7c1984135b5838c9c22d031e28a14675c09e06d1 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 26 Aug 2023 11:30:51 -0400 Subject: [PATCH 1/9] docs: add detailed parameter listing, change interface to modules there are a few changes here - documentation of each parameter separately has been added to the generated text docs - interfaces have been renamed to modules. this was honestly a pointless and confusing distinction (interfaces are tables for modules that are lua modules). it also makes it so that (formerly) interfaces and modules line up with each other on the doc list im not sure what else i did, these are old changes --- cmd/docgen/docgen.go | 45 ++++++++++++++-- docs/api/bait.md | 25 +++++++-- docs/api/commander.md | 8 ++- docs/api/fs.md | 36 +++++++++---- docs/api/hilbish/_index.md | 72 ++++++++++++++++++------- docs/api/hilbish/hilbish.aliases.md | 18 +++++-- docs/api/hilbish/hilbish.completions.md | 18 +++++-- docs/api/hilbish/hilbish.editor.md | 18 +++++-- docs/api/hilbish/hilbish.history.md | 22 +++++--- docs/api/hilbish/hilbish.jobs.md | 22 +++++--- docs/api/hilbish/hilbish.os.md | 2 +- docs/api/hilbish/hilbish.runner.md | 14 +++-- docs/api/hilbish/hilbish.timers.md | 10 ++-- docs/api/hilbish/hilbish.userDir.md | 2 +- docs/api/terminal.md | 16 ++++-- golibs/bait/bait.go | 2 + 16 files changed, 253 insertions(+), 77 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index aae6202..9008cca 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -43,6 +43,12 @@ type module struct { HasTypes bool } +type param struct{ + Name string + Type string + Doc []string +} + type docPiece struct { Doc []string FuncSig string @@ -55,6 +61,7 @@ type docPiece struct { IsType bool Fields []docPiece Properties []docPiece + Params []param } type tag struct { @@ -215,6 +222,17 @@ start: fields := docPieceTag("field", tags) properties := docPieceTag("property", tags) + var params []param + if paramsRaw := tags["param"]; paramsRaw != nil { + params = make([]param, len(paramsRaw)) + for i, p := range paramsRaw { + params[i] = param{ + Name: p.id, + Type: p.fields[0], + Doc: p.fields[1:], + } + } + } for _, d := range doc { if strings.HasPrefix(d, "---") { @@ -252,6 +270,7 @@ start: ParentModule: parentMod, Fields: fields, Properties: properties, + Params: params, } if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) { dps.Doc = parts @@ -412,7 +431,7 @@ func main() { defer wg.Done() modOrIface := "Module" if modu.ParentModule != "" { - modOrIface = "Interface" + modOrIface = "Module" } f, _ := os.Create(docPath) @@ -454,7 +473,7 @@ func main() { if dps.IsMember { continue } - htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string { + htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(modname + "." + dps.FuncSig, "<", `\<`, -1), func(typ string) string { typName := typ[1:] typLookup := typeTable[strings.ToLower(typName)] ifaces := typLookup[0] + "." + typLookup[1] + "/" @@ -462,7 +481,7 @@ func main() { ifaces = "" } linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s#%s", typLookup[0], ifaces, strings.ToLower(typName)) - return fmt.Sprintf(`%s`, linkedTyp, typName) + return fmt.Sprintf(`%s`, linkedTyp, typName) }) f.WriteString(fmt.Sprintf("### %s\n", htmlSig)) for _, doc := range dps.Doc { @@ -470,6 +489,26 @@ func main() { f.WriteString(doc + "\n") } } + f.WriteString("#### Parameters\n") + if len(dps.Params) == 0 { + f.WriteString("This function has no parameters. \n") + } + for _, p := range dps.Params { + isVariadic := false + typ := p.Type + if strings.HasPrefix(p.Type, "...") { + isVariadic = true + typ = p.Type[3:] + } + + f.WriteString(fmt.Sprintf("`%s` **`%s`**", typ, p.Name)) + if isVariadic { + f.WriteString(" (This type is variadic. You can pass an infinite amount of parameters with this type.)") + } + f.WriteString(" \n") + f.WriteString(strings.Join(p.Doc, " ")) + f.WriteString("\n\n") + } f.WriteString("\n") } } diff --git a/docs/api/bait.md b/docs/api/bait.md index a70eb17..5929bbd 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -15,20 +15,35 @@ happened, like when you've changed directory, a command has failed, etc. To find all available hooks thrown by Hilbish, see doc hooks. ## Functions -### catch(name, cb) +### bait.catch(name, cb) Catches a hook with `name`. Runs the `cb` when it is thrown +#### Parameters +This function has no parameters. -### catchOnce(name, cb) +### bait.catchOnce(name, cb) Same as catch, but only runs the `cb` once and then removes the hook +#### Parameters +This function has no parameters. -### hooks(name) -> table +### bait.hooks(name) -> table Returns a table with hooks (callback functions) on the event with `name`. +#### Parameters +This function has no parameters. -### release(name, catcher) +### bait.release(name, catcher) Removes the `catcher` for the event with `name`. For this to work, `catcher` has to be the same function used to catch an event, like one saved to a variable. +#### Parameters +This function has no parameters. -### throw(name, ...args) +### bait.throw(name, ...args) Throws a hook with `name` with the provided `args` +#### Parameters +`string` **`name`** +The name of the hook. + +`any` **`args`** (This type is variadic. You can pass an infinite amount of parameters with this type.) +The arguments to pass to the hook. + diff --git a/docs/api/commander.md b/docs/api/commander.md index 341eeda..aa0849e 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -38,9 +38,13 @@ output should go. name would suggest. ## Functions -### deregister(name) +### commander.deregister(name) Deregisters any command registered with `name` +#### Parameters +This function has no parameters. -### register(name, cb) +### commander.register(name, cb) Register a command with `name` that runs `cb` when ran +#### Parameters +This function has no parameters. diff --git a/docs/api/fs.md b/docs/api/fs.md index ee6949f..e6e8f87 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -13,39 +13,57 @@ and other things, and acts an addition to the Lua standard library's I/O and filesystem functions. ## Functions -### abs(path) -> string +### fs.abs(path) -> string Gives an absolute version of `path`. +#### Parameters +This function has no parameters. -### basename(path) -> string +### fs.basename(path) -> string Gives the basename of `path`. For the rules, see Go's filepath.Base +#### Parameters +This function has no parameters. -### cd(dir) +### fs.cd(dir) Changes directory to `dir` +#### Parameters +This function has no parameters. -### dir(path) -> string +### fs.dir(path) -> string Returns the directory part of `path`. For the rules, see Go's filepath.Dir +#### Parameters +This function has no parameters. -### glob(pattern) -> matches (table) +### fs.glob(pattern) -> matches (table) Glob all files and directories that match the pattern. For the rules, see Go's filepath.Glob +#### Parameters +This function has no parameters. -### join(...) -> string +### fs.join(...) -> string Takes paths and joins them together with the OS's directory separator (forward or backward slash). +#### Parameters +This function has no parameters. -### mkdir(name, recursive) +### fs.mkdir(name, recursive) Makes a directory called `name`. If `recursive` is true, it will create its parent directories. +#### Parameters +This function has no parameters. -### readdir(dir) -> {} +### fs.readdir(dir) -> {} Returns a table of files in `dir`. +#### Parameters +This function has no parameters. -### stat(path) -> {} +### fs.stat(path) -> {} Returns a table of info about the `path`. It contains the following keys: name (string) - Name of the path size (number) - Size of the path mode (string) - Permission mode in an octal format string (with leading 0) isDir (boolean) - If the path is a directory +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 4cf0180..9ebd21a 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -23,29 +23,41 @@ interfaces and functions which directly relate to shell functionality. - `exitCode`: xit code of the last executed command ## Functions -### alias(cmd, orig) +### hilbish.alias(cmd, orig) Sets an alias of `cmd` to `orig` +#### Parameters +This function has no parameters. -### appendPath(dir) +### hilbish.appendPath(dir) Appends `dir` to $PATH +#### Parameters +This function has no parameters. -### complete(scope, cb) +### hilbish.complete(scope, cb) Registers a completion handler for `scope`. A `scope` is currently only expected to be `command.`, replacing with the name of the command (for example `command.git`). `cb` must be a function that returns a table of "completion groups." Check `doc completions` for more information. +#### Parameters +This function has no parameters. -### cwd() -> string +### hilbish.cwd() -> string Returns the current directory of the shell +#### Parameters +This function has no parameters. -### exec(cmd) +### hilbish.exec(cmd) Replaces running hilbish with `cmd` +#### Parameters +This function has no parameters. -### goro(fn) +### hilbish.goro(fn) Puts `fn` in a goroutine +#### Parameters +This function has no parameters. -### highlighter(line) +### hilbish.highlighter(line) Line highlighter handler. This is mainly for syntax highlighting, but in reality could set the input of the prompt to *display* anything. The callback is passed the current line and is expected to return a line that @@ -58,59 +70,83 @@ function hilbish.highlighter(line) end ``` This code will highlight all double quoted strings in green. +#### Parameters +This function has no parameters. -### hinter(line, pos) +### hilbish.hinter(line, pos) The command line hint handler. It gets called on every key insert to determine what text to use as an inline hint. It is passed the current line and cursor position. It is expected to return a string which is used as the text for the hint. This is by default a shim. To set hints, override this function with your custom handler. +#### Parameters +This function has no parameters. -### inputMode(mode) +### hilbish.inputMode(mode) Sets the input mode for Hilbish's line reader. Accepts either emacs or vim +#### Parameters +This function has no parameters. -### interval(cb, time) -> Timer +### hilbish.interval(cb, time) -> Timer Runs the `cb` function every `time` milliseconds. This creates a timer that starts immediately. +#### Parameters +This function has no parameters. -### multiprompt(str) +### hilbish.multiprompt(str) Changes the continued line prompt to `str` +#### Parameters +This function has no parameters. -### prependPath(dir) +### hilbish.prependPath(dir) Prepends `dir` to $PATH +#### Parameters +This function has no parameters. -### prompt(str, typ) +### hilbish.prompt(str, typ) Changes the shell prompt to `str` There are a few verbs that can be used in the prompt text. These will be formatted and replaced with the appropriate values. `%d` - Current working directory `%u` - Name of current user `%h` - Hostname of device +#### Parameters +This function has no parameters. -### read(prompt) -> input (string) +### hilbish.read(prompt) -> input (string) Read input from the user, using Hilbish's line editor/input reader. This is a separate instance from the one Hilbish actually uses. Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) +#### Parameters +This function has no parameters. -### run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string) +### hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string) Runs `cmd` in Hilbish's sh interpreter. If returnOut is true, the outputs of `cmd` will be returned as the 2nd and 3rd values instead of being outputted to the terminal. +#### Parameters +This function has no parameters. -### runnerMode(mode) +### hilbish.runnerMode(mode) Sets the execution/runner mode for interactive Hilbish. This determines whether Hilbish wll try to run input as Lua and/or sh or only do one of either. Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), sh, and lua. It also accepts a function, to which if it is passed one will call it to execute user input instead. +#### Parameters +This function has no parameters. -### timeout(cb, time) -> Timer +### hilbish.timeout(cb, time) -> Timer Runs the `cb` function after `time` in milliseconds. This creates a timer that starts immediately. +#### Parameters +This function has no parameters. -### which(name) -> string +### hilbish.which(name) -> string Checks if `name` is a valid command. Will return the path of the binary, or a basename if it's a commander. +#### Parameters +This function has no parameters. ## Types ## Sink diff --git a/docs/api/hilbish/hilbish.aliases.md b/docs/api/hilbish/hilbish.aliases.md index bae5bfc..1936b47 100644 --- a/docs/api/hilbish/hilbish.aliases.md +++ b/docs/api/hilbish/hilbish.aliases.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.aliases +title: Module hilbish.aliases description: command aliasing layout: doc menu: @@ -11,15 +11,23 @@ menu: The alias interface deals with all command aliases in Hilbish. ## Functions -### add(alias, cmd) +### hilbish.aliases.add(alias, cmd) This is an alias (ha) for the `hilbish.alias` function. +#### Parameters +This function has no parameters. -### delete(name) +### hilbish.aliases.delete(name) Removes an alias. +#### Parameters +This function has no parameters. -### list() -> table\ +### hilbish.aliases.list() -> table\ Get a table of all aliases, with string keys as the alias and the value as the command. +#### Parameters +This function has no parameters. -### resolve(alias) -> command (string) +### hilbish.aliases.resolve(alias) -> command (string) Tries to resolve an alias to its command. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 6f8740f..6ec1206 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.completions +title: Module hilbish.completions description: tab completions layout: doc menu: @@ -11,19 +11,27 @@ menu: The completions interface deals with tab completions. ## Functions -### call(name, query, ctx, fields) -> completionGroups (table), prefix (string) +### hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string) Calls a completer function. This is mainly used to call a command completer, which will have a `name` in the form of `command.name`, example: `command.git`. You can check `doc completions` for info on the `completionGroups` return value. +#### Parameters +This function has no parameters. -### handler(line, pos) +### hilbish.completions.handler(line, pos) The handler function is the callback for tab completion in Hilbish. You can check the completions doc for more info. +#### Parameters +This function has no parameters. -### bins(query, ctx, fields) -> entries (table), prefix (string) +### hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string) Returns binary/executale completion candidates based on the provided query. +#### Parameters +This function has no parameters. -### files(query, ctx, fields) -> entries (table), prefix (string) +### hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string) Returns file completion candidates based on the provided query. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 30a3842..e10aca9 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.editor +title: Module hilbish.editor description: interactions for Hilbish's line reader layout: doc menu: @@ -12,15 +12,23 @@ The hilbish.editor interface provides functions to directly interact with the line editor in use. ## Functions -### getLine() -> string +### hilbish.editor.getLine() -> string Returns the current input line. +#### Parameters +This function has no parameters. -### getVimRegister(register) -> string +### hilbish.editor.getVimRegister(register) -> string Returns the text that is at the register. +#### Parameters +This function has no parameters. -### insert(text) +### hilbish.editor.insert(text) Inserts text into the line. +#### Parameters +This function has no parameters. -### setVimRegister(register, text) +### hilbish.editor.setVimRegister(register, text) Sets the vim register at `register` to hold the passed text. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 9fa9b01..902155f 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.history +title: Module hilbish.history description: command history layout: doc menu: @@ -13,18 +13,28 @@ This includes the ability to override functions to change the main method of saving history. ## Functions -### add(cmd) +### hilbish.history.add(cmd) Adds a command to the history. +#### Parameters +This function has no parameters. -### all() -> table +### hilbish.history.all() -> table Retrieves all history. +#### Parameters +This function has no parameters. -### clear() +### hilbish.history.clear() Deletes all commands from the history. +#### Parameters +This function has no parameters. -### get(idx) +### hilbish.history.get(idx) Retrieves a command from the history based on the `idx`. +#### Parameters +This function has no parameters. -### size() -> number +### hilbish.history.size() -> number Returns the amount of commands in the history. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index e41be2c..5f8992d 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.jobs +title: Module hilbish.jobs description: background job management layout: doc menu: @@ -15,20 +15,30 @@ Jobs are the name of background tasks/commands. A job can be started via interactive usage or with the functions defined below for use in external runners. ## Functions -### add(cmdstr, args, execPath) +### hilbish.jobs.add(cmdstr, args, execPath) Adds a new job to the job table. Note that this does not immediately run it. +#### Parameters +This function has no parameters. -### all() -> table\<Job> +### hilbish.jobs.all() -> table\<Job> Returns a table of all job objects. +#### Parameters +This function has no parameters. -### disown(id) +### hilbish.jobs.disown(id) Disowns a job. This deletes it from the job table. +#### Parameters +This function has no parameters. -### get(id) -> Job +### hilbish.jobs.get(id) -> Job Get a job object via its ID. +#### Parameters +This function has no parameters. -### last() -> Job +### hilbish.jobs.last() -> Job Returns the last added job from the table. +#### Parameters +This function has no parameters. ## Types ## Job diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index aa2198e..00196da 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.os +title: Module hilbish.os description: OS Info layout: doc menu: diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 68ffdc6..7729bdd 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.runner +title: Module hilbish.runner description: interactive command runner customization layout: doc menu: @@ -15,17 +15,23 @@ language or script of their choosing. A good example is using it to write command in Fennel. ## Functions -### setMode(cb) +### hilbish.runner.setMode(cb) This is the same as the `hilbish.runnerMode` function. It takes a callback, which will be used to execute all interactive input. In normal cases, neither callbacks should be overrided by the user, as the higher level functions listed below this will handle it. +#### Parameters +This function has no parameters. -### lua(cmd) +### hilbish.runner.lua(cmd) Evaluates `cmd` as Lua input. This is the same as using `dofile` or `load`, but is appropriated for the runner interface. +#### Parameters +This function has no parameters. -### sh(cmd) +### hilbish.runner.sh(cmd) Runs a command in Hilbish's shell script interpreter. This is the equivalent of using `source`. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index e899d1d..576c820 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.timers +title: Module hilbish.timers description: timeout and interval API layout: doc menu: @@ -35,12 +35,16 @@ print(t.running) // true - `TIMEOUT`: Constant for a timeout timer type ## Functions -### create(type, time, callback) -> Timer +### hilbish.timers.create(type, time, callback) -> Timer Creates a timer that runs based on the specified `time` in milliseconds. The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` +#### Parameters +This function has no parameters. -### get(id) -> Timer +### hilbish.timers.get(id) -> Timer Retrieves a timer via its ID. +#### Parameters +This function has no parameters. ## Types ## Timer diff --git a/docs/api/hilbish/hilbish.userDir.md b/docs/api/hilbish/hilbish.userDir.md index 0b95057..0c1d7d0 100644 --- a/docs/api/hilbish/hilbish.userDir.md +++ b/docs/api/hilbish/hilbish.userDir.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.userDir +title: Module hilbish.userDir description: user-related directories layout: doc menu: diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 99d4b49..5ad24c7 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -11,16 +11,24 @@ menu: The terminal library is a simple and lower level library for certain terminal interactions. ## Functions -### restoreState() +### terminal.restoreState() Restores the last saved state of the terminal +#### Parameters +This function has no parameters. -### saveState() +### terminal.saveState() Saves the current state of the terminal +#### Parameters +This function has no parameters. -### setRaw() +### terminal.setRaw() Puts the terminal in raw mode +#### Parameters +This function has no parameters. -### size() +### terminal.size() Gets the dimensions of the terminal. Returns a table with `width` and `height` Note: this is not the size in relation to the dimensions of the display +#### Parameters +This function has no parameters. diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 3f3c34e..4ba2a37 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -229,6 +229,8 @@ func handleHook(t *rt.Thread, c *rt.GoCont, name string, catcher *rt.Closure, ar } // throw(name, ...args) +// #param name string The name of the hook. +// #param args ...any The arguments to pass to the hook. // Throws a hook with `name` with the provided `args` // --- @param name string // --- @vararg any From 81b7e20cbf7388cc8483b202a1db11e77f494933 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 12:57:13 -0400 Subject: [PATCH 2/9] docs: add better introduction for bait module also highlights codeblocks better --- cmd/docgen/docgen.go | 2 +- docs/api/bait.md | 32 +++++-- golibs/bait/bait.go | 33 +++++-- website/config.toml | 3 + website/themes/hsh/assets/css/syntax.css | 85 +++++++++++++++++++ website/themes/hsh/layouts/partials/head.html | 3 + 6 files changed, 144 insertions(+), 14 deletions(-) create mode 100644 website/themes/hsh/assets/css/syntax.css diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 9008cca..11f41db 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -437,7 +437,7 @@ func main() { f, _ := os.Create(docPath) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) typeTag, _ := regexp.Compile(`@\w+`) - modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(modu.Description, "<", `\<`, -1), func(typ string) string { + modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(strings.Replace(modu.Description, "<", `\<`, -1), "{{\\<", "{{<", -1), func(typ string) string { typName := typ[1:] typLookup := typeTable[strings.ToLower(typName)] ifaces := typLookup[0] + "." + typLookup[1] + "/" diff --git a/docs/api/bait.md b/docs/api/bait.md index 5929bbd..c464563 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -8,17 +8,37 @@ menu: --- ## Introduction -Bait is the event emitter for Hilbish. Why name it bait? Why not. -It throws hooks that you can catch. This is what you will use if -you want to listen in on hooks to know when certain things have -happened, like when you've changed directory, a command has failed, -etc. To find all available hooks thrown by Hilbish, see doc hooks. + +Bait is the event emitter for Hilbish. Much like Node.js and +its `events` system, many actions in Hilbish emit events. +Unlike Node.js, Hilbish events are global. So make sure to +pick a unique name! + +Usage of the Bait module consists of userstanding +event-driven architecture, but it's pretty simple: +If you want to act on a certain event, you can `catch` it. +You can act on events via callback functions. + +Examples of this are in the Hilbish default config! +Consider this part of it: +``` +bait.catch('command.exit', function(code) + running = false + doPrompt(code ~= 0) + doNotifyPrompt() +end) +``` + +What this does is, whenever the `command.exit` event is thrown, +this function will set the user prompt. ## Functions ### bait.catch(name, cb) Catches a hook with `name`. Runs the `cb` when it is thrown #### Parameters -This function has no parameters. +`string` **`name`** +ummm + ### bait.catchOnce(name, cb) Same as catch, but only runs the `cb` once and then removes the hook diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 4ba2a37..269ea1e 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -1,9 +1,28 @@ // the event emitter -// Bait is the event emitter for Hilbish. Why name it bait? Why not. -// It throws hooks that you can catch. This is what you will use if -// you want to listen in on hooks to know when certain things have -// happened, like when you've changed directory, a command has failed, -// etc. To find all available hooks thrown by Hilbish, see doc hooks. +/* +Bait is the event emitter for Hilbish. Much like Node.js and +its `events` system, many actions in Hilbish emit events. +Unlike Node.js, Hilbish events are global. So make sure to +pick a unique name! + +Usage of the Bait module consists of userstanding +event-driven architecture, but it's pretty simple: +If you want to act on a certain event, you can `catch` it. +You can act on events via callback functions. + +Examples of this are in the Hilbish default config! +Consider this part of it: +``` +bait.catch('command.exit', function(code) + running = false + doPrompt(code ~= 0) + doNotifyPrompt() +end) +``` + +What this does is, whenever the `command.exit` event is thrown, +this function will set the user prompt. +*/ package bait import ( @@ -253,8 +272,8 @@ func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // catch(name, cb) // Catches a hook with `name`. Runs the `cb` when it is thrown -// --- @param name string -// --- @param cb function +// #param name string ummm +// #param cb function ? func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { diff --git a/website/config.toml b/website/config.toml index 31f42d5..0ae7ff2 100644 --- a/website/config.toml +++ b/website/config.toml @@ -29,6 +29,9 @@ enableGitInfo = true [markup.goldmark.renderer] unsafe = true +[markup.highlight] +style = 'pastie' + [author] [author.sammyette] name = 'sammyette' diff --git a/website/themes/hsh/assets/css/syntax.css b/website/themes/hsh/assets/css/syntax.css new file mode 100644 index 0000000..724106a --- /dev/null +++ b/website/themes/hsh/assets/css/syntax.css @@ -0,0 +1,85 @@ +/* Background */ .bg { background-color: #ffffff; } +/* PreWrapper */ .chroma { background-color: #ffffff; } +/* Other */ .chroma .x { } +/* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 } +/* CodeLine */ .chroma .cl { } +/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; } +/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; } +/* LineHighlight */ .chroma .hl { background-color: #ffffcc } +/* LineNumbersTable */ .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } +/* LineNumbers */ .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } +/* Line */ .chroma .line { display: flex; } +/* Keyword */ .chroma .k { color: #008800; font-weight: bold } +/* KeywordConstant */ .chroma .kc { color: #008800; font-weight: bold } +/* KeywordDeclaration */ .chroma .kd { color: #008800; font-weight: bold } +/* KeywordNamespace */ .chroma .kn { color: #008800; font-weight: bold } +/* KeywordPseudo */ .chroma .kp { color: #008800 } +/* KeywordReserved */ .chroma .kr { color: #008800; font-weight: bold } +/* KeywordType */ .chroma .kt { color: #888888; font-weight: bold } +/* Name */ .chroma .n { } +/* NameAttribute */ .chroma .na { color: #336699 } +/* NameBuiltin */ .chroma .nb { color: #003388 } +/* NameBuiltinPseudo */ .chroma .bp { } +/* NameClass */ .chroma .nc { color: #bb0066; font-weight: bold } +/* NameConstant */ .chroma .no { color: #003366; font-weight: bold } +/* NameDecorator */ .chroma .nd { color: #555555 } +/* NameEntity */ .chroma .ni { } +/* NameException */ .chroma .ne { color: #bb0066; font-weight: bold } +/* NameFunction */ .chroma .nf { color: #0066bb; font-weight: bold } +/* NameFunctionMagic */ .chroma .fm { } +/* NameLabel */ .chroma .nl { color: #336699; font-style: italic } +/* NameNamespace */ .chroma .nn { color: #bb0066; font-weight: bold } +/* NameOther */ .chroma .nx { } +/* NameProperty */ .chroma .py { color: #336699; font-weight: bold } +/* NameTag */ .chroma .nt { color: #bb0066; font-weight: bold } +/* NameVariable */ .chroma .nv { color: #336699 } +/* NameVariableClass */ .chroma .vc { color: #336699 } +/* NameVariableGlobal */ .chroma .vg { color: #dd7700 } +/* NameVariableInstance */ .chroma .vi { color: #3333bb } +/* NameVariableMagic */ .chroma .vm { } +/* Literal */ .chroma .l { } +/* LiteralDate */ .chroma .ld { } +/* LiteralString */ .chroma .s { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringAffix */ .chroma .sa { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringBacktick */ .chroma .sb { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringChar */ .chroma .sc { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringDelimiter */ .chroma .dl { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringDoc */ .chroma .sd { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringDouble */ .chroma .s2 { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringEscape */ .chroma .se { color: #0044dd; background-color: #fff0f0 } +/* LiteralStringHeredoc */ .chroma .sh { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringInterpol */ .chroma .si { color: #3333bb; background-color: #fff0f0 } +/* LiteralStringOther */ .chroma .sx { color: #22bb22; background-color: #f0fff0 } +/* LiteralStringRegex */ .chroma .sr { color: #008800; background-color: #fff0ff } +/* LiteralStringSingle */ .chroma .s1 { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringSymbol */ .chroma .ss { color: #aa6600; background-color: #fff0f0 } +/* LiteralNumber */ .chroma .m { color: #0000dd; font-weight: bold } +/* LiteralNumberBin */ .chroma .mb { color: #0000dd; font-weight: bold } +/* LiteralNumberFloat */ .chroma .mf { color: #0000dd; font-weight: bold } +/* LiteralNumberHex */ .chroma .mh { color: #0000dd; font-weight: bold } +/* LiteralNumberInteger */ .chroma .mi { color: #0000dd; font-weight: bold } +/* LiteralNumberIntegerLong */ .chroma .il { color: #0000dd; font-weight: bold } +/* LiteralNumberOct */ .chroma .mo { color: #0000dd; font-weight: bold } +/* Operator */ .chroma .o { } +/* OperatorWord */ .chroma .ow { color: #008800 } +/* Punctuation */ .chroma .p { } +/* Comment */ .chroma .c { color: #888888 } +/* CommentHashbang */ .chroma .ch { color: #888888 } +/* CommentMultiline */ .chroma .cm { color: #888888 } +/* CommentSingle */ .chroma .c1 { color: #888888 } +/* CommentSpecial */ .chroma .cs { color: #cc0000; background-color: #fff0f0; font-weight: bold } +/* CommentPreproc */ .chroma .cp { color: #cc0000; font-weight: bold } +/* CommentPreprocFile */ .chroma .cpf { color: #cc0000; font-weight: bold } +/* Generic */ .chroma .g { } +/* GenericDeleted */ .chroma .gd { color: #000000; background-color: #ffdddd } +/* GenericEmph */ .chroma .ge { font-style: italic } +/* GenericError */ .chroma .gr { color: #aa0000 } +/* GenericHeading */ .chroma .gh { color: #333333 } +/* GenericInserted */ .chroma .gi { color: #000000; background-color: #ddffdd } +/* GenericOutput */ .chroma .go { color: #888888 } +/* GenericPrompt */ .chroma .gp { color: #555555 } +/* GenericStrong */ .chroma .gs { font-weight: bold } +/* GenericSubheading */ .chroma .gu { color: #666666 } +/* GenericTraceback */ .chroma .gt { color: #aa0000 } +/* GenericUnderline */ .chroma .gl { text-decoration: underline } +/* TextWhitespace */ .chroma .w { color: #bbbbbb } diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index fca4558..cb2e12e 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -23,7 +23,10 @@ + {{ $syntax := resources.Get "css/syntax.css" | resources.Minify | resources.Fingerprint }} + + From 22cf0fcb4951e2ea6d5cd17f81d5d6daa995e1d8 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 14:30:31 -0400 Subject: [PATCH 4/9] docs: change colors for syntax highlight and function jump highlight --- website/themes/hsh/assets/css/syntax.css | 6 +++--- website/themes/hsh/layouts/partials/head.html | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/themes/hsh/assets/css/syntax.css b/website/themes/hsh/assets/css/syntax.css index 724106a..021dcb3 100644 --- a/website/themes/hsh/assets/css/syntax.css +++ b/website/themes/hsh/assets/css/syntax.css @@ -1,11 +1,11 @@ -/* Background */ .bg { background-color: #ffffff; } -/* PreWrapper */ .chroma { background-color: #ffffff; } +/* Background */ .bg { background-color: #edfdff; } +/* PreWrapper */ .chroma { background-color: #edfdff; } /* Other */ .chroma .x { } /* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 } /* CodeLine */ .chroma .cl { } /* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; } /* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; } -/* LineHighlight */ .chroma .hl { background-color: #ffffcc } +/* LineHighlight */ .chroma .hl { background-color: #edfdff } /* LineNumbersTable */ .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } /* LineNumbers */ .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } /* Line */ .chroma .line { display: flex; } diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index 087d997..8299693 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -43,7 +43,7 @@ background: none } 50% { - background: yellow; + background: #fff2cf; } 100% { background: none; @@ -51,7 +51,7 @@ } div:target { - animation: highlight 1s; + animation: highlight 1.2s; animation-timing-function: cubic-bezier(1,-0.02,.45,.89); } From eda4fda972cf93e4fbd73e040a22ec516cf8dbc0 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 15:32:53 -0400 Subject: [PATCH 5/9] docs(commander): remove note about input sink being unimplemented --- docs/api/commander.md | 2 +- golibs/commander/commander.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/commander.md b/docs/api/commander.md index 72140ad..fa641b4 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -31,7 +31,7 @@ The `sinks` parameter is a table with 3 keys: `in`, `out`, and `err`. The values of these is a Sink. - `in` is the standard input. You can read from this sink -to get user input. (**This is currently unimplemented.**) +to get user input. - `out` is standard output. This is usually where text meant for output should go. - `err` is standard error. This sink is for writing errors, as the diff --git a/golibs/commander/commander.go b/golibs/commander/commander.go index c639cf9..a21de1c 100644 --- a/golibs/commander/commander.go +++ b/golibs/commander/commander.go @@ -22,7 +22,7 @@ The `sinks` parameter is a table with 3 keys: `in`, `out`, and `err`. The values of these is a @Sink. - `in` is the standard input. You can read from this sink -to get user input. (**This is currently unimplemented.**) +to get user input. - `out` is standard output. This is usually where text meant for output should go. - `err` is standard error. This sink is for writing errors, as the From 090028430426009ec8d7c200fecda28e425406d9 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 16:01:57 -0400 Subject: [PATCH 6/9] docs: turn properties list into a table also fix member functions causing a spam of separators --- cmd/docgen/docgen.go | 19 ++-- docs/api/bait.md | 20 +++- docs/api/commander.md | 8 +- docs/api/fs.md | 36 +++++-- docs/api/hilbish/_index.md | 93 +++++++++++++------ docs/api/hilbish/hilbish.aliases.md | 16 +++- docs/api/hilbish/hilbish.completions.md | 16 +++- docs/api/hilbish/hilbish.editor.md | 16 +++- docs/api/hilbish/hilbish.history.md | 20 +++- docs/api/hilbish/hilbish.jobs.md | 21 ++++- docs/api/hilbish/hilbish.os.md | 8 +- docs/api/hilbish/hilbish.runner.md | 12 ++- docs/api/hilbish/hilbish.timers.md | 15 ++- docs/api/hilbish/hilbish.userDir.md | 6 +- docs/api/terminal.md | 16 +++- website/themes/hsh/layouts/partials/head.html | 1 + 16 files changed, 236 insertions(+), 87 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index a14742d..9332dfa 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -481,11 +481,17 @@ func main() { if len(modu.Fields) != 0 { f.WriteString("## Interface fields\n") - for _, dps := range modu.Fields { - f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) - f.WriteString(strings.Join(dps.Doc, " ")) - f.WriteString("\n") + + mdTable := md.NewTable(len(modu.Fields), 2) + mdTable.SetTitle(0, "") + mdTable.SetTitle(1, "") + + + for i, dps := range modu.Fields { + mdTable.SetContent(i, 0, dps.FuncName) + mdTable.SetContent(i, 1, strings.Join(dps.Doc, " ")) } + f.WriteString(mdTable.String()) f.WriteString("\n") } if len(modu.Properties) != 0 { @@ -499,12 +505,12 @@ func main() { } if len(modu.Docs) != 0 { - //f.WriteString("## Functions\n") + f.WriteString("## Functions\n") for _, dps := range modu.Docs { - f.WriteString(fmt.Sprintf("
", dps.FuncName)) if dps.IsMember { continue } + f.WriteString(fmt.Sprintf("
", dps.FuncName)) htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(modname + "." + dps.FuncSig, "<", `\<`, -1), func(typ string) string { typName := typ[1:] typLookup := typeTable[strings.ToLower(typName)] @@ -550,6 +556,7 @@ func main() { f.WriteString("\n\n") } f.WriteString("
") + f.WriteString("\n\n") } } diff --git a/docs/api/bait.md b/docs/api/bait.md index 292152f..468648f 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -41,6 +41,7 @@ this function will set the user prompt. |release(name, catcher)|Removes the `catcher` for the event with `name`.| |throw(name, ...args)|Throws a hook with `name` with the provided `args`| +## Functions

bait.catch(name, cb) @@ -57,7 +58,9 @@ ummm `function` **`cb`** ? -

+
+ +
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/commander.md b/docs/api/commander.md index fa641b4..20117af 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -43,6 +43,7 @@ name would suggest. |deregister(name)|Deregisters any command registered with `name`| |register(name, cb)|Register a command with `name` that runs `cb` when ran| +## Functions

commander.deregister(name) @@ -54,7 +55,9 @@ commander.deregister(name) Deregisters any command registered with `name` #### Parameters This function has no parameters. -

+
+ +
\ No newline at end of file + + diff --git a/docs/api/fs.md b/docs/api/fs.md index 64a2092..fff8877 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -25,6 +25,7 @@ I/O and filesystem functions. |readdir(dir) -> {}|Returns a table of files in `dir`.| |stat(path) -> {}|Returns a table of info about the `path`.| +## Functions

fs.abs(path) -> string @@ -36,7 +37,9 @@ fs.abs(path) -> string Gives an absolute version of `path`. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
 \ No newline at end of file + + diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 317ba5d..2fb9aa7 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -34,16 +34,19 @@ interfaces and functions which directly relate to shell functionality. |which(name) -> string|Checks if `name` is a valid command.| ## Interface fields -- `ver`: The version of Hilbish -- `goVersion`: The version of Go that Hilbish was compiled with -- `user`: Username of the user -- `host`: Hostname of the machine -- `dataDir`: Directory for Hilbish data files, including the docs and default modules -- `interactive`: Is Hilbish in an interactive shell? -- `login`: Is Hilbish the login shell? -- `vimMode`: Current Vim input mode of Hilbish (will be nil if not in Vim input mode) -- `exitCode`: xit code of the last executed command +||| +|----|----| +|ver|The version of Hilbish| +|goVersion|The version of Go that Hilbish was compiled with| +|user|Username of the user| +|host|Hostname of the machine| +|dataDir|Directory for Hilbish data files, including the docs and default modules| +|interactive|Is Hilbish in an interactive shell?| +|login|Is Hilbish the login shell?| +|vimMode|Current Vim input mode of Hilbish (will be nil if not in Vim input mode)| +|exitCode|xit code of the last executed command| +## Functions

hilbish.alias(cmd, orig) @@ -55,7 +58,9 @@ hilbish.alias(cmd, orig) Sets an alias of `cmd` to `orig` #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
 + diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 726e7e9..698140d 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -18,6 +18,7 @@ The completions interface deals with tab completions. |bins(query, ctx, fields) -> entries (table), prefix (string)|Returns binary/executale completion candidates based on the provided query.| |files(query, ctx, fields) -> entries (table), prefix (string)|Returns file completion candidates based on the provided query.| +## Functions

hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string) @@ -32,7 +33,9 @@ of `command.name`, example: `command.git`. You can check `doc completions` for info on the `completionGroups` return value. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 38b247e..ee55580 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -19,6 +19,7 @@ directly interact with the line editor in use. |insert(text)|Inserts text into the line.| |setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.| +## Functions

hilbish.editor.getLine() -> string @@ -30,7 +31,9 @@ hilbish.editor.getLine() -> string Returns the current input line. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 0f60370..dee087a 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -21,6 +21,7 @@ method of saving history. |get(idx)|Retrieves a command from the history based on the `idx`.| |size() -> number|Returns the amount of commands in the history.| +## Functions

hilbish.history.add(cmd) @@ -32,7 +33,9 @@ hilbish.history.add(cmd) Adds a command to the history. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index f27bc98..ecc045e 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -23,6 +23,7 @@ interactive usage or with the functions defined below for use in external runner |get(id) -> @Job|Get a job object via its ID.| |last() -> @Job|Returns the last added job from the table.| +## Functions

hilbish.jobs.add(cmdstr, args, execPath) @@ -34,7 +35,9 @@ hilbish.jobs.add(cmdstr, args, execPath) Adds a new job to the job table. Note that this does not immediately run it. #### Parameters This function has no parameters. -

+
+ +
+ +

hilbish.jobs.get(id) -> Job @@ -67,7 +74,9 @@ hilbish.jobs.get(id) ->
+
+ +
 + +## Types ## Job The Job type describes a Hilbish job. ### Properties diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 00196da..3abd8f7 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -13,7 +13,9 @@ the current OS on the systen. This mainly includes the name and version. ## Interface fields -- `family`: Family name of the current OS -- `name`: Pretty name of the current OS -- `version`: Version of the current OS +||| +|----|----| +|family|Family name of the current OS| +|name|Pretty name of the current OS| +|version|Version of the current OS| diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index f5977e1..98e8f6c 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -21,6 +21,7 @@ write command in Fennel. |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| +## Functions

hilbish.runner.setMode(cb) @@ -35,7 +36,9 @@ In normal cases, neither callbacks should be overrided by the user, as the higher level functions listed below this will handle it. #### Parameters This function has no parameters. -

+
+ +
+ +
 \ No newline at end of file +

+ diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 20efd7c..186c1af 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -37,9 +37,12 @@ print(t.running) // true |get(id) -> @Timer|Retrieves a timer via its ID.| ## Interface fields -- `INTERVAL`: Constant for an interval timer type -- `TIMEOUT`: Constant for a timeout timer type +||| +|----|----| +|INTERVAL|Constant for an interval timer type| +|TIMEOUT|Constant for a timeout timer type| +## Functions

hilbish.timers.create(type, time, callback) -> Timer @@ -52,7 +55,9 @@ Creates a timer that runs based on the specified `time` in milliseconds. The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` #### Parameters This function has no parameters. -

+
+ +
+ diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index 8299693..6109fb5 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -60,6 +60,7 @@ border-style: solid; border-color: #565c64;; border-collapse: collapse; + margin-bottom: 12px; } table td { From 7fd2ed391b17b143bf908b721e8696fd26006698 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 16:11:57 -0400 Subject: [PATCH 7/9] docs: add separators for types, make object properties into tables --- cmd/docgen/docgen.go | 33 ++++++++++++++++++++--------- docs/api/hilbish/_index.md | 6 ++++-- docs/api/hilbish/hilbish.jobs.md | 23 ++++++++++++-------- docs/api/hilbish/hilbish.os.md | 2 +- docs/api/hilbish/hilbish.timers.md | 17 +++++++++------ docs/api/hilbish/hilbish.userDir.md | 2 +- 6 files changed, 54 insertions(+), 29 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 9332dfa..8598091 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -480,7 +480,7 @@ func main() { } if len(modu.Fields) != 0 { - f.WriteString("## Interface fields\n") + f.WriteString("## Static module fields\n") mdTable := md.NewTable(len(modu.Fields), 2) mdTable.SetTitle(0, "") @@ -496,11 +496,17 @@ func main() { } if len(modu.Properties) != 0 { f.WriteString("## Object properties\n") - for _, dps := range modu.Properties { - f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) - f.WriteString(strings.Join(dps.Doc, " ")) - f.WriteString("\n") + + mdTable := md.NewTable(len(modu.Fields), 2) + mdTable.SetTitle(0, "") + mdTable.SetTitle(1, "") + + + for i, dps := range modu.Properties { + mdTable.SetContent(i, 0, dps.FuncName) + mdTable.SetContent(i, 1, strings.Join(dps.Doc, " ")) } + f.WriteString(mdTable.String()) f.WriteString("\n") } @@ -563,6 +569,7 @@ func main() { if len(modu.Types) != 0 { f.WriteString("## Types\n") for _, dps := range modu.Types { + f.WriteString("
\n\n") f.WriteString(fmt.Sprintf("## %s\n", dps.FuncName)) for _, doc := range dps.Doc { if !strings.HasPrefix(doc, "---") { @@ -570,12 +577,18 @@ func main() { } } if len(dps.Properties) != 0 { - f.WriteString("### Properties\n") - for _, dps := range dps.Properties { - f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) - f.WriteString(strings.Join(dps.Doc, " ")) - f.WriteString("\n") + f.WriteString("## Object properties\n") + + mdTable := md.NewTable(len(dps.Properties), 2) + mdTable.SetTitle(0, "") + mdTable.SetTitle(1, "") + + for i, d := range dps.Properties { + mdTable.SetContent(i, 0, d.FuncName) + mdTable.SetContent(i, 1, strings.Join(d.Doc, " ")) } + f.WriteString(mdTable.String()) + f.WriteString("\n") } f.WriteString("\n") f.WriteString("### Methods\n") diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 2fb9aa7..3bfb92b 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -33,7 +33,7 @@ interfaces and functions which directly relate to shell functionality. |timeout(cb, time) -> @Timer|Runs the `cb` function after `time` in milliseconds.| |which(name) -> string|Checks if `name` is a valid command.| -## Interface fields +## Static module fields ||| |----|----| |ver|The version of Hilbish| @@ -316,7 +316,9 @@ Will return the path of the binary, or a basename if it's a commander. This function has no parameters.
-
## Types +## Types +
+ ## Sink A sink is a structure that has input and/or output to/from a desination. diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index ecc045e..290fe6f 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -24,7 +24,7 @@ interactive usage or with the functions defined below for use in external runner |last() -> @Job|Returns the last added job from the table.| ## Functions -
+

hilbish.jobs.add(cmdstr, args, execPath) @@ -90,16 +90,21 @@ This function has no parameters.

## Types +
+ ## Job The Job type describes a Hilbish job. -### Properties -- `cmd`: The user entered command string for the job. -- `running`: Whether the job is running or not. -- `id`: The ID of the job in the job table -- `pid`: The Process ID -- `exitCode`: The last exit code of the job. -- `stdout`: The standard output of the job. This just means the normal logs of the process. -- `stderr`: The standard error stream of the process. This (usually) includes error messages of the job. +## Object properties +||| +|----|----| +|cmd|The user entered command string for the job.| +|running|Whether the job is running or not.| +|id|The ID of the job in the job table| +|pid|The Process ID| +|exitCode|The last exit code of the job.| +|stdout|The standard output of the job. This just means the normal logs of the process.| +|stderr|The standard error stream of the process. This (usually) includes error messages of the job.| + ### Methods #### background() diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 3abd8f7..7749e3d 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -12,7 +12,7 @@ The `os` interface provides simple text information properties about the current OS on the systen. This mainly includes the name and version. -## Interface fields +## Static module fields ||| |----|----| |family|Family name of the current OS| diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 186c1af..f996bb4 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -36,14 +36,14 @@ print(t.running) // true |create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time` in milliseconds.| |get(id) -> @Timer|Retrieves a timer via its ID.| -## Interface fields +## Static module fields ||| |----|----| |INTERVAL|Constant for an interval timer type| |TIMEOUT|Constant for a timeout timer type| ## Functions -
+

hilbish.timers.create(type, time, callback) -> Timer @@ -71,12 +71,17 @@ This function has no parameters.

## Types +
+ ## Timer The Job type describes a Hilbish timer. -### Properties -- `type`: What type of timer it is -- `running`: If the timer is running -- `duration`: The duration in milliseconds that the timer will run +## Object properties +||| +|----|----| +|type|What type of timer it is| +|running|If the timer is running| +|duration|The duration in milliseconds that the timer will run| + ### Methods #### start() diff --git a/docs/api/hilbish/hilbish.userDir.md b/docs/api/hilbish/hilbish.userDir.md index 2fd60f6..a2b7337 100644 --- a/docs/api/hilbish/hilbish.userDir.md +++ b/docs/api/hilbish/hilbish.userDir.md @@ -12,7 +12,7 @@ This interface just contains properties to know about certain user directories. It is equivalent to XDG on Linux and gets the user's preferred directories for configs and data. -## Interface fields +## Static module fields ||| |----|----| |config|The user's config directory| From 95ac2e280daaeac7b34ecc6360ebbbe5a92cf971 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 16:24:35 -0400 Subject: [PATCH 8/9] docs: fix description of exitCode prop --- api.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api.go b/api.go index 61aac21..2f0a548 100644 --- a/api.go +++ b/api.go @@ -9,7 +9,7 @@ // #field interactive Is Hilbish in an interactive shell? // #field login Is Hilbish the login shell? // #field vimMode Current Vim input mode of Hilbish (will be nil if not in Vim input mode) -// #field exitCode xit code of the last executed command +// #field exitCode Exit code of the last executed command package main import ( From 726082ba032309b80b27d8ba63ea0a215f7cae91 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 9 Sep 2023 13:38:54 -0400 Subject: [PATCH 9/9] docs: fix duplicate functions header --- cmd/docgen/docgen.go | 6 +++++- docs/api/bait.md | 1 - docs/api/commander.md | 1 - docs/api/fs.md | 1 - docs/api/hilbish/_index.md | 1 - docs/api/hilbish/hilbish.aliases.md | 1 - docs/api/hilbish/hilbish.completions.md | 1 - docs/api/hilbish/hilbish.editor.md | 1 - docs/api/hilbish/hilbish.history.md | 1 - docs/api/hilbish/hilbish.jobs.md | 1 - docs/api/hilbish/hilbish.runner.md | 1 - docs/api/hilbish/hilbish.timers.md | 1 - docs/api/terminal.md | 1 - 13 files changed, 5 insertions(+), 13 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 8598091..487af9f 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -435,6 +435,7 @@ func main() { if modu.ParentModule != "" { modOrIface = "Module" } + lastHeader := "" f, _ := os.Create(docPath) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) @@ -460,6 +461,7 @@ func main() { } f.WriteString("## Functions\n") + lastHeader = "functions" mdTable := md.NewTable(funcCount, 2) mdTable.SetTitle(0, "") @@ -511,7 +513,9 @@ func main() { } if len(modu.Docs) != 0 { - f.WriteString("## Functions\n") + if lastHeader != "functions" { + f.WriteString("## Functions\n") + } for _, dps := range modu.Docs { if dps.IsMember { continue diff --git a/docs/api/bait.md b/docs/api/bait.md index 468648f..91cfb31 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -41,7 +41,6 @@ this function will set the user prompt. |release(name, catcher)|Removes the `catcher` for the event with `name`.| |throw(name, ...args)|Throws a hook with `name` with the provided `args`| -## Functions

bait.catch(name, cb) diff --git a/docs/api/commander.md b/docs/api/commander.md index 20117af..4d67c81 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -43,7 +43,6 @@ name would suggest. |deregister(name)|Deregisters any command registered with `name`| |register(name, cb)|Register a command with `name` that runs `cb` when ran| -## Functions

commander.deregister(name) diff --git a/docs/api/fs.md b/docs/api/fs.md index fff8877..37045eb 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -25,7 +25,6 @@ I/O and filesystem functions. |readdir(dir) -> {}|Returns a table of files in `dir`.| |stat(path) -> {}|Returns a table of info about the `path`.| -## Functions

fs.abs(path) -> string diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 3bfb92b..36e6413 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -46,7 +46,6 @@ interfaces and functions which directly relate to shell functionality. |vimMode|Current Vim input mode of Hilbish (will be nil if not in Vim input mode)| |exitCode|xit code of the last executed command| -## Functions

hilbish.alias(cmd, orig) diff --git a/docs/api/hilbish/hilbish.aliases.md b/docs/api/hilbish/hilbish.aliases.md index b5d27a2..5274e04 100644 --- a/docs/api/hilbish/hilbish.aliases.md +++ b/docs/api/hilbish/hilbish.aliases.md @@ -18,7 +18,6 @@ The alias interface deals with all command aliases in Hilbish. |list() -> table|Get a table of all aliases, with string keys as the alias and the value as the command.| |resolve(alias) -> command (string)|Tries to resolve an alias to its command.| -## Functions

hilbish.aliases.add(alias, cmd) diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 698140d..790aeee 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -18,7 +18,6 @@ The completions interface deals with tab completions. |bins(query, ctx, fields) -> entries (table), prefix (string)|Returns binary/executale completion candidates based on the provided query.| |files(query, ctx, fields) -> entries (table), prefix (string)|Returns file completion candidates based on the provided query.| -## Functions

hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string) diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index ee55580..282737d 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -19,7 +19,6 @@ directly interact with the line editor in use. |insert(text)|Inserts text into the line.| |setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.| -## Functions

hilbish.editor.getLine() -> string diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index dee087a..3d9b856 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -21,7 +21,6 @@ method of saving history. |get(idx)|Retrieves a command from the history based on the `idx`.| |size() -> number|Returns the amount of commands in the history.| -## Functions

hilbish.history.add(cmd) diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index 290fe6f..bb1af1e 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -23,7 +23,6 @@ interactive usage or with the functions defined below for use in external runner |get(id) -> @Job|Get a job object via its ID.| |last() -> @Job|Returns the last added job from the table.| -## Functions

hilbish.jobs.add(cmdstr, args, execPath) diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 98e8f6c..5528195 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -21,7 +21,6 @@ write command in Fennel. |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| -## Functions

hilbish.runner.setMode(cb) diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index f996bb4..dae7782 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -42,7 +42,6 @@ print(t.running) // true |INTERVAL|Constant for an interval timer type| |TIMEOUT|Constant for a timeout timer type| -## Functions

hilbish.timers.create(type, time, callback) -> Timer diff --git a/docs/api/terminal.md b/docs/api/terminal.md index c5cb5ea..4977e97 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -18,7 +18,6 @@ The terminal library is a simple and lower level library for certain terminal in |setRaw()|Puts the terminal in raw mode| |size()|Gets the dimensions of the terminal. Returns a table with `width` and `height`| -## Functions

terminal.restoreState()