feat!: enhance docs and doc command

changes the actual file format of docs
to markup since that's basically what we have been
using in the first place.

the docgen command has been modified to write
markdown headings with the function name and
yaml metadata for easy consumption by hugo for the
website (soon).

all other docs have been moved to markdown as well
this is the main reason this is a "breaking" change
users will have to reinstall hilbish
(task uninstall and task install) to remove the old
plaintext docs

cmd/docgen/docgen.go

@@ -11,11 +11,25 @@ import (
 	"os"
 )
 
+var header = `---
+name: Module %s
+description: %s
+layout: apidoc
+---
+
+`
+
 type EmmyPiece struct {
 	FuncName string
 	Docs []string
 	Params []string // we only need to know param name to put in function
 }
+
+type Module struct {
+	Docs []DocPiece
+	ShortDescription string
+	Description string
+}
 type DocPiece struct {
 	Doc []string
 	FuncSig string
@@ -27,8 +41,8 @@ type DocPiece struct {
 func main() {
 	fset := token.NewFileSet()
 	os.Mkdir("docs", 0777)
+	os.Mkdir("docs/api", 0777)
 	os.Mkdir("emmyLuaDocs", 0777)
-	
 
 	dirs := []string{"./"}
 	filepath.Walk("golibs/", func (path string, info os.FileInfo, err error) error {
@@ -58,11 +72,12 @@ func main() {
 		"bait": "b",
 		"terminal": "term",
 	}
-	docs := make(map[string][]DocPiece)
+	docs := make(map[string]Module)
 	emmyDocs := make(map[string][]EmmyPiece)
 
 	for l, f := range pkgs {
 		p := doc.New(f, "./", doc.AllDecls)
+		pieces := []DocPiece{}
 		for _, t := range p.Funcs {
 			mod := l
 			if strings.HasPrefix(t.Name, "hl") { mod = "hilbish" }
@@ -95,7 +110,7 @@ func main() {
 				FuncName: strings.TrimPrefix(t.Name, prefix[mod]),
 			}
 			
-			docs[mod] = append(docs[mod], dps)
+			pieces = append(pieces, dps)
 			emmyDocs[mod] = append(emmyDocs[mod], em)
 		}
 		for _, t := range p.Types {
@@ -128,17 +143,28 @@ func main() {
 					FuncName: strings.TrimPrefix(m.Name, prefix[l]),
 				}
 
-				docs[l] = append(docs[l], dps)
+				pieces = append(pieces, dps)
 				emmyDocs[l] = append(emmyDocs[l], em)
 			}
 		}
+
+		descParts := strings.Split(strings.TrimSpace(p.Doc), "\n")
+		shortDesc := descParts[0]
+		desc := descParts[1:]
+		docs[l] = Module{
+			Docs: pieces,
+			ShortDescription: shortDesc,
+			Description: strings.Join(desc, "\n"),
+		}
 	}
 
 	for mod, v := range docs {
 		if mod == "main" { continue }
-		f, _ := os.Create("docs/" + mod + ".txt")
-		for _, dps := range v {
-			f.WriteString(dps.FuncSig + " > ")
+		f, _ := os.Create("docs/api/" + mod + ".md")
+		f.WriteString(fmt.Sprintf(header, mod, v.ShortDescription))
+		f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n## Functions\n", v.Description))
+		for _, dps := range v.Docs {
+			f.WriteString(fmt.Sprintf("### %s\n", dps.FuncSig))
 			for _, doc := range dps.Doc {
 				if !strings.HasPrefix(doc, "---") {
 					f.WriteString(doc + "\n")
@@ -154,7 +180,7 @@ func main() {
 		f.WriteString("--- @meta\n\nlocal " + mod + " = {}\n\n")
 		for _, em := range v {
 			var funcdocs []string
-			for _, dps := range docs[mod] {
+			for _, dps := range docs[mod].Docs {
 				if dps.FuncName == em.FuncName {
 					funcdocs = dps.Doc
 				}

docs/api/bait.md

@@ -0,0 +1,31 @@
+---
+name: Module bait
+description: the event emitter
+layout: apidoc
+---
+
+## 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.
+
+## Functions
+### catch(name, cb)
+Catches a hook with `name`. Runs the `cb` when it is thrown
+
+### catchOnce(name, cb)
+Same as catch, but only runs the `cb` once and then removes the hook
+
+### hooks(name) -> {cb, cb...}
+Returns a table with hooks on the event with `name`.
+
+### 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.
+
+### throw(name, ...args)
+Throws a hook with `name` with the provided `args`
+

docs/api/commander.md

@@ -0,0 +1,16 @@
+---
+name: Module commander
+description: library for custom commands
+layout: apidoc
+---
+
+## Introduction
+Commander is a library for writing custom commands in Lua.
+
+## Functions
+### deregister(name)
+Deregisters any command registered with `name`
+
+### register(name, cb)
+Register a command with `name` that runs `cb` when ran
+

docs/api/fs.md

@@ -0,0 +1,41 @@
+---
+name: Module fs
+description: 
+layout: apidoc
+---
+
+## Introduction
+
+
+## Functions
+### abs(path)
+Gives an absolute version of `path`.
+
+### basename(path)
+Gives the basename of `path`. For the rules,
+see Go's filepath.Base
+
+### cd(dir)
+Changes directory to `dir`
+
+### dir(path)
+Returns the directory part of `path`. For the rules, see Go's
+filepath.Dir
+
+### glob(pattern)
+Glob all files and directories that match the pattern.
+For the rules, see Go's filepath.Glob
+
+### join(paths...)
+Takes paths and joins them together with the OS's
+directory separator (forward or backward slash).
+
+### mkdir(name, recursive)
+Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
+
+### readdir(dir)
+Returns a table of files in `dir`
+
+### stat(path)
+Returns info about `path`
+

docs/api/hilbish.md

@@ -1,62 +1,84 @@
-alias(cmd, orig) > Sets an alias of `cmd` to `orig`
+---
+name: Module hilbish
+---
 
-appendPath(dir) > Appends `dir` to $PATH
+### alias(cmd, orig)
+Sets an alias of `cmd` to `orig`
 
-complete(scope, cb) > Registers a completion handler for `scope`.
+### appendPath(dir)
+Appends `dir` to $PATH
+
+### complete(scope, cb)
+Registers a completion handler for `scope`.
 A `scope` is currently only expected to be `command.<cmd>`,
 replacing <cmd> 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.
 
-cwd() > Returns the current directory of the shell
+### cwd()
+Returns the current directory of the shell
 
-exec(cmd) > Replaces running hilbish with `cmd`
+### exec(cmd)
+Replaces running hilbish with `cmd`
 
-goro(fn) > Puts `fn` in a goroutine
+### goro(fn)
+Puts `fn` in a goroutine
 
-highlighter(line) > Line highlighter handler. This is mainly for syntax highlighting, but in
+### 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
 will be used as the input display.
 
-hinter(line, pos) > The command line hint handler. It gets called on every key insert to
+### 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.
 
-inputMode(mode) > Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
+### inputMode(mode)
+Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
 
-interval(cb, time) > Runs the `cb` function every `time` milliseconds.
+### interval(cb, time)
+Runs the `cb` function every `time` milliseconds.
 Returns a `timer` object (see `doc timers`).
 
-multiprompt(str) > Changes the continued line prompt to `str`
+### multiprompt(str)
+Changes the continued line prompt to `str`
 
-prependPath(dir) > Prepends `dir` to $PATH
+### prependPath(dir)
+Prepends `dir` to $PATH
 
-prompt(str, typ?) > Changes the shell prompt to `str`
+### 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
 
-read(prompt?) -> input? > Read input from the user, using Hilbish's line editor/input reader.
+### read(prompt?) -> input?
+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)
 
-run(cmd, returnOut) -> exitCode, stdout, stderr > Runs `cmd` in Hilbish's sh interpreter.
+### run(cmd, returnOut) -> exitCode, stdout, stderr
+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.
 
-runnerMode(mode) > Sets the execution/runner mode for interactive Hilbish. This determines whether
+### 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.
 
-timeout(cb, time) > Runs the `cb` function after `time` in milliseconds
+### timeout(cb, time)
+Runs the `cb` function after `time` in milliseconds
 Returns a `timer` object (see `doc timers`).
 
-which(name) > Checks if `name` is a valid command
+### which(name)
+Checks if `name` is a valid command
 

docs/api/terminal.md

@@ -0,0 +1,23 @@
+---
+name: Module terminal
+description: 
+layout: apidoc
+---
+
+## Introduction
+
+
+## Functions
+### restoreState()
+Restores the last saved state of the terminal
+
+### saveState()
+Saves the current state of the terminal
+
+### setRaw()
+Puts the terminal in raw mode
+
+### 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
+

docs/bait.txt

@@ -1,12 +0,0 @@
-catch(name, cb) > Catches a hook with `name`. Runs the `cb` when it is thrown
-
-catchOnce(name, cb) > Same as catch, but only runs the `cb` once and then removes the hook
-
-hooks(name) -> {cb, cb...} > Returns a table with hooks on the event with `name`.
-
-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.
-
-throw(name, ...args) > Throws a hook with `name` with the provided `args`
-

docs/commander.txt

@@ -1,4 +0,0 @@
-deregister(name) > Deregisters any command registered with `name`
-
-register(name, cb) > Register a command with `name` that runs `cb` when ran
-

docs/fs.txt

@@ -1,22 +0,0 @@
-abs(path) > Gives an absolute version of `path`.
-
-basename(path) > Gives the basename of `path`. For the rules,
-see Go's filepath.Base
-
-cd(dir) > Changes directory to `dir`
-
-dir(path) > Returns the directory part of `path`. For the rules, see Go's
-filepath.Dir
-
-glob(pattern) > Glob all files and directories that match the pattern.
-For the rules, see Go's filepath.Glob
-
-join(paths...) > Takes paths and joins them together with the OS's
-directory separator (forward or backward slash).
-
-mkdir(name, recursive) > Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
-
-readdir(dir) > Returns a table of files in `dir`
-
-stat(path) > Returns info about `path`
-

docs/terminal.txt

@@ -1,9 +0,0 @@
-restoreState() > Restores the last saved state of the terminal
-
-saveState() > Saves the current state of the terminal
-
-setRaw() > Puts the terminal in raw mode
-
-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
-

emmyLuaDocs/hilbish.lua

@@ -2,108 +2,82 @@
 
 local hilbish = {}
 
---- Sets an alias of `cmd` to `orig`
+--- 
 --- @param cmd string
 --- @param orig string
 function hilbish.alias(cmd, orig) end
 
---- Appends `dir` to $PATH
+--- 
 --- @param dir string|table
 function hilbish.appendPath(dir) end
 
---- Registers a completion handler for `scope`.
---- A `scope` is currently only expected to be `command.<cmd>`,
---- replacing <cmd> 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.
+--- 
 --- @param scope string
 --- @param cb function
 function hilbish.complete(scope, cb) end
 
---- Returns the current directory of the shell
+--- 
 function hilbish.cwd() end
 
---- Replaces running hilbish with `cmd`
+--- 
 --- @param cmd string
 function hilbish.exec(cmd) end
 
---- Puts `fn` in a goroutine
+--- 
 --- @param fn function
 function hilbish.goro(fn) end
 
---- 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
---- will be used as the input display.
+--- 
 --- @param line string
 function hilbish.highlighter(line) end
 
---- 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.
+--- 
 --- @param line string
 --- @param pos int
 function hilbish.hinter(line, pos) end
 
---- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
+--- 
 --- @param mode string
 function hilbish.inputMode(mode) end
 
---- Runs the `cb` function every `time` milliseconds.
---- Returns a `timer` object (see `doc timers`).
+--- 
 --- @param cb function
 --- @param time number
 --- @return table
 function hilbish.interval(cb, time) end
 
---- Changes the continued line prompt to `str`
+--- 
 --- @param str string
 function hilbish.multiprompt(str) end
 
---- Prepends `dir` to $PATH
+--- 
 --- @param dir string
 function hilbish.prependPath(dir) end
 
---- 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
+--- 
 --- @param str string
 --- @param typ string Type of prompt, being left or right. Left by default.
 function hilbish.prompt(str, typ) end
 
---- 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)
+--- 
 --- @param prompt string
 function hilbish.read(prompt) end
 
---- 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.
+--- 
 --- @param cmd string
 function hilbish.run(cmd) end
 
---- 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.
+--- 
 --- @param mode string|function
 function hilbish.runnerMode(mode) end
 
---- Runs the `cb` function after `time` in milliseconds
---- Returns a `timer` object (see `doc timers`).
+--- 
 --- @param cb function
 --- @param time number
 --- @return table
 function hilbish.timeout(cb, time) end
 
---- Checks if `name` is a valid command
+--- 
 --- @param binName string
 function hilbish.which(binName) end
 

golibs/bait/bait.go

@@ -1,3 +1,9 @@
+// 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.
 package bait
 
 import (

golibs/commander/commander.go

@@ -1,3 +1,5 @@
+// library for custom commands
+// Commander is a library for writing custom commands in Lua.
 package commander
 
 import (

libs/lunacolors

@@ -1 +1 @@
-Subproject commit 8467b87dd8d49c68b4100b2d129d5f071544b8cf
+Subproject commit cc271b6145e7cab91513cc7afdb0cc523e8878aa

nature/commands/doc.lua

@@ -4,34 +4,34 @@ local lunacolors = require 'lunacolors'
 
 commander.register('doc', function(args)
 	local moddocPath = hilbish.dataDir .. '/docs/'
-	local modDocFormat = [[
-%s
-%s
-# Functions
+	local apidocHeader = [[
+# %s
+{grayBg}  {white}{italic}%s  {reset}
+
 ]]
 
 	if #args > 0 then
 		local mod = args[1]
 
-		local f = io.open(moddocPath .. mod .. '.txt', 'rb')
+		local f = io.open(moddocPath .. mod .. '.md', 'rb')
 		local funcdocs = nil
 		if not f then
 			-- assume subdir
-			-- dataDir/docs/<mod>/<mod>.txt
+			-- dataDir/docs/<mod>/<mod>.md
 			moddocPath = moddocPath .. mod .. '/'
 			local subdocName = args[2]
 			if not subdocName then
 				subdocName = 'index'
 			end
-			f = io.open(moddocPath .. subdocName .. '.txt', 'rb')
+			f = io.open(moddocPath .. subdocName .. '.md', 'rb')
 			if not f then
 				print('No documentation found for ' .. mod .. '.')
 				return
 			end
 			funcdocs = f:read '*a'
-			local moddocs = table.filter(fs.readdir(moddocPath), function(f) return f ~= 'index.txt' end)
+			local moddocs = table.filter(fs.readdir(moddocPath), function(f) return f ~= 'index.md' end)
 			local subdocs = table.map(moddocs, function(fname)
-				return lunacolors.underline(lunacolors.blue(string.gsub(fname, '.txt', '')))
+				return lunacolors.underline(lunacolors.blue(string.gsub(fname, '.md', '')))
 			end)
 			if subdocName == 'index' then
 				funcdocs = funcdocs .. '\nSubdocs: ' .. table.concat(subdocs, ', ')
@@ -41,8 +41,24 @@ commander.register('doc', function(args)
 		if not funcdocs then
 			funcdocs = f:read '*a'
 		end
-		local desc = ''
-		local ok = pcall(require, mod)
+		local valsStr = funcdocs:match '%-%-%-\n([^%-%-%-]+)\n'
+		local vals = {}
+		if valsStr then
+			local _, endpos = funcdocs:find('---\n' .. valsStr .. '\n---\n\n', 1, true)
+			funcdocs = funcdocs:sub(endpos + 1, #funcdocs)
+
+			-- parse vals
+			local lines = string.split(valsStr, '\n')
+			for _, line in ipairs(lines) do
+				local key = line:match '(%w+): '
+				local val = line:match '^%w+: (.-)$'
+
+				vals[key] = val
+			end
+		end
+		if mod == 'api' then
+			funcdocs = string.format(apidocHeader, vals.name, vals.description) .. funcdocs
+		end
 		local backtickOccurence = 0
 		local formattedFuncs = lunacolors.format(funcdocs:sub(1, #funcdocs - 1):gsub('`', function()
 			backtickOccurence = backtickOccurence + 1
@@ -51,34 +67,16 @@ commander.register('doc', function(args)
 			else
 				return '{underline}{green}'
 			end
+		end):gsub('#+.-\n', function(t)
+			return '{bold}{magenta}' .. t .. '{reset}'
 		end))
-
-		if ok then
-			local props = {}
-			local propstr = ''
-			local modDesc = ''
-			local modmt = getmetatable(require(mod))
-			if modmt then
-				modDesc = modmt.__doc
-				if modmt.__docProp then
-					-- not all modules have docs for properties
-					props = table.map(modmt.__docProp, function(v, k)
-						return lunacolors.underline(lunacolors.blue(k)) .. ' > ' .. v
-					end)
-				end
-				if #props > 0 then
-					propstr = '\n# Properties\n' .. table.concat(props, '\n') .. '\n'
-				end
-				desc = string.format(modDocFormat, modDesc, propstr)
-			end
-		end
-		print(desc .. formattedFuncs)
+		print(formattedFuncs)
 		f:close()
 
 		return
 	end
 	local modules = table.map(fs.readdir(moddocPath), function(f)
-		return lunacolors.underline(lunacolors.blue(string.gsub(f, '.txt', '')))
+		return lunacolors.underline(lunacolors.blue(string.gsub(f, '.md', '')))
 	end)
 
 	io.write [[