diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index bf8fd1b..4743dea 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -299,7 +299,25 @@ start: func main() { fset := token.NewFileSet() os.Mkdir("docs", 0777) + os.RemoveAll("docs/api") os.Mkdir("docs/api", 0777) + + f, err := os.Create("docs/api/_index.md") + if err != nil { + panic(err) + } + f.WriteString(`--- +title: API +layout: doc +weight: -100 +menu: docs +--- + +Welcome to the API documentation for Hilbish. This documents Lua functions +provided by Hilbish. +`) + f.Close() + os.Mkdir("emmyLuaDocs", 0777) dirs := []string{"./"} diff --git a/cmd/docgen/docgen.lua b/cmd/docgen/docgen.lua index 62c4619..5f25937 100644 --- a/cmd/docgen/docgen.lua +++ b/cmd/docgen/docgen.lua @@ -1,7 +1,9 @@ local fs = require 'fs' local emmyPattern = '^%-%-%- (.+)' +local emmyPattern2 = '^%-%- (.+)' local modpattern = '^%-+ @module (.+)' local pieces = {} +local descriptions = {} local files = fs.readdir 'nature' for _, fname in ipairs(files) do @@ -15,16 +17,24 @@ for _, fname in ipairs(files) do print(fname, mod) pieces[mod] = {} + descriptions[mod] = {} local docPiece = {} local lines = {} local lineno = 0 + local doingDescription = true + for line in f:lines() do lineno = lineno + 1 lines[lineno] = line if line == header then goto continue2 end - if not line:match(emmyPattern) then + if line:match(emmyPattern) or line:match(emmyPattern2) then + if doingDescription then + table.insert(descriptions[mod], line:match(emmyPattern) or line:match(emmyPattern2)) + end + else + doingDescription = false if line:match '^function' then local pattern = (string.format('^function %s%%.', mod) .. '(%w+)') local funcName = line:match(pattern) @@ -107,7 +117,12 @@ for iface, dps in pairs(pieces) do local f = io.open(path, newOrNotNature and 'r+' or 'w+') if not newOrNotNature then - f:write(string.format(header, 'Module', iface, 'No description.', docParent)) + f:write(string.format(header, 'Module', iface, (descriptions[iface] and #descriptions[iface] > 0) and descriptions[iface][1] or 'No description.', docParent)) + if descriptions[iface] and #descriptions[iface] > 0 then + table.remove(descriptions[iface], 1) + f:write(string.format('\n## Introduction\n%s\n\n', table.concat(descriptions[iface], '\n'))) + f:write('## Functions\n') + end end print(f) diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md deleted file mode 100644 index fe3978f..0000000 --- a/docs/api/hilbish/hilbish.jobs.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Module hilbish.jobs -description: background job management -layout: doc -menu: - docs: - parent: "API" ---- - -## Introduction - -Manage interactive jobs in Hilbish via Lua. - -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)|Creates a new job. This function does not run the job. This function is intended to be| -|all() -> table[@Job]|Returns a table of all job objects.| -|disown(id)|Disowns a job. This simply deletes it from the list of jobs without stopping it.| -|get(id) -> @Job|Get a job object via its ID.| -|last() -> @Job|Returns the last added job to the table.| - -
-
-

-hilbish.jobs.add(cmdstr, args, execPath) - - - -

- -Creates a new job. This function does not run the job. This function is intended to be -used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs. - -#### Parameters -`string` **`cmdstr`** -String that a user would write for the job - -`table` **`args`** -Arguments for the commands. Has to include the name of the command. - -`string` **`execPath`** -Binary to use to run the command. Needs to be an absolute path. - -#### Example -```lua -hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go') -``` -
- -
-
-

-hilbish.jobs.all() -> table[Job] - - - -

- -Returns a table of all job objects. - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.jobs.disown(id) - - - -

- -Disowns a job. This simply deletes it from the list of jobs without stopping it. - -#### Parameters -`number` **`id`** - - -
- -
-
-

-hilbish.jobs.get(id) -> Job - - - -

- -Get a job object via its ID. - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.jobs.last() -> Job - - - -

- -Returns the last added job to the table. - -#### Parameters -This function has no parameters. -
- -## Types -
- -## Job -The Job type describes a Hilbish 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() -Puts a job in the background. This acts the same as initially running a job. - -#### foreground() -Puts a job in the foreground. This will cause it to run like it was -executed normally and wait for it to complete. - -#### start() -Starts running the job. - -#### stop() -Stops the job from running. - diff --git a/docs/api/hilbish/hilbish.messages.md b/docs/api/hilbish/hilbish.messages.md index 538b6c0..e36119b 100644 --- a/docs/api/hilbish/hilbish.messages.md +++ b/docs/api/hilbish/hilbish.messages.md @@ -1,1529 +1,25 @@ --- title: Module hilbish.messages -description: No description. +description: simplistic message passing layout: doc menu: docs: parent: "API" --- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -r - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -e - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -r - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -e - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -r - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -e - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -r - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -e - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -r - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -e - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** -r - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** -e - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** - - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** - - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** - - -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** - - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete() - - - -

- -Deletes the message at `idx`. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.read() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** - - -
- -
-
-

-hilbish.messages.readAll() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- - -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- -Returns all messages. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- -Deletes all messages. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** - - -
- -
-
-

-hilbish.messages.read(idx) - - - -

- -Marks a message at `idx` as read. -#### Parameters -`idx` **`number`** - - -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** - - -
- -
-
-

-hilbish.messages.readAll() - - - -

- -Marks all messages as read. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- -Returns the amount of unread messages. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.all() - - - -

- -Returns all messages. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.clear() - - - -

- -Deletes all messages. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.delete(idx) - - - -

- -Deletes the message at `idx`. -#### Parameters -`idx` **`number`** - - -
- -
-
-

-hilbish.messages.read(idx) - - - -

- -Marks a message at `idx` as read. -#### Parameters -`idx` **`number`** - - -
- -
-
-

-hilbish.messages.send(message) - - - -

- -Sends a message. -#### Parameters -`message` **`hilbish.message`** - - -
- -
-
-

-hilbish.messages.readAll() - - - -

- -Marks all messages as read. -#### Parameters -This function has no parameters. -
- -
-
-

-hilbish.messages.unreadCount() - - - -

- -Returns the amount of unread messages. -#### Parameters -This function has no parameters. -
+## Introduction +The messages interface defines a way for Hilbish-integrated commands, +user config and other tasks to send notifications to alert the user.z +The `hilbish.message` type is a table with the following keys: +`title` (string): A title for the message notification. +`text` (string): The contents of the message. +`channel` (string): States the origin of the message, `hilbish.*` is reserved for Hilbish tasks. +`summary` (string): A short summary of the `text`. +`icon` (string): Unicode (preferably standard emoji) icon for the message notification +`read` (boolean): Whether the full message has been read or not. + +## Functions

diff --git a/docs/nature/dirs.md b/docs/nature/dirs.md index 8b52f8a..27540ce 100644 --- a/docs/nature/dirs.md +++ b/docs/nature/dirs.md @@ -1,12 +1,18 @@ --- title: Module dirs -description: No description. +description: internal directory management layout: doc menu: docs: parent: "Nature" --- + +## Introduction +The dirs module defines a small set of functions to store and manage +directories. + +## Functions

diff --git a/docs/nature/doc.md b/docs/nature/doc.md index b508240..15cc6d1 100644 --- a/docs/nature/doc.md +++ b/docs/nature/doc.md @@ -1,12 +1,20 @@ --- title: Module doc -description: No description. +description: command-line doc rendering layout: doc menu: docs: parent: "Nature" --- + +## Introduction +The doc module contains a small set of functions +used by the Greenhouse pager to render parts of the documentation pages. +This is only documented for the sake of it. It's only intended use +is by the Greenhouse pager. + +## Functions