diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 39a2a76..5a3f1f3 100644 --- a/cmd/docgen/docgen.go +++ b/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 } diff --git a/docs/api/bait.md b/docs/api/bait.md new file mode 100644 index 0000000..2eaaffe --- /dev/null +++ b/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` + diff --git a/docs/api/commander.md b/docs/api/commander.md new file mode 100644 index 0000000..379ecba --- /dev/null +++ b/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 + diff --git a/docs/api/fs.md b/docs/api/fs.md new file mode 100644 index 0000000..e2f0e62 --- /dev/null +++ b/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` + diff --git a/docs/hilbish.txt b/docs/api/hilbish.md similarity index 55% rename from docs/hilbish.txt rename to docs/api/hilbish.md index 20a9bd7..baba4aa 100644 --- a/docs/hilbish.txt +++ b/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.`, 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. -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 diff --git a/docs/api/terminal.md b/docs/api/terminal.md new file mode 100644 index 0000000..dacc879 --- /dev/null +++ b/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 + diff --git a/docs/bait.txt b/docs/bait.txt deleted file mode 100644 index 2b6f7ae..0000000 --- a/docs/bait.txt +++ /dev/null @@ -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` - diff --git a/docs/commander.txt b/docs/commander.txt deleted file mode 100644 index 8b4b329..0000000 --- a/docs/commander.txt +++ /dev/null @@ -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 - diff --git a/docs/completions.txt b/docs/completions.md similarity index 100% rename from docs/completions.txt rename to docs/completions.md diff --git a/docs/fs.txt b/docs/fs.txt deleted file mode 100644 index 8372afd..0000000 --- a/docs/fs.txt +++ /dev/null @@ -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` - diff --git a/docs/hooks/command.txt b/docs/hooks/command.md similarity index 100% rename from docs/hooks/command.txt rename to docs/hooks/command.md diff --git a/docs/hooks/hilbish.txt b/docs/hooks/hilbish.md similarity index 100% rename from docs/hooks/hilbish.txt rename to docs/hooks/hilbish.md diff --git a/docs/hooks/index.txt b/docs/hooks/index.md similarity index 100% rename from docs/hooks/index.txt rename to docs/hooks/index.md diff --git a/docs/hooks/job.txt b/docs/hooks/job.md similarity index 100% rename from docs/hooks/job.txt rename to docs/hooks/job.md diff --git a/docs/hooks/signal.txt b/docs/hooks/signal.md similarity index 100% rename from docs/hooks/signal.txt rename to docs/hooks/signal.md diff --git a/docs/jobs.txt b/docs/jobs.md similarity index 100% rename from docs/jobs.txt rename to docs/jobs.md diff --git a/docs/lunacolors.txt b/docs/lunacolors.md similarity index 100% rename from docs/lunacolors.txt rename to docs/lunacolors.md diff --git a/docs/nature/index.txt b/docs/nature/index.md similarity index 100% rename from docs/nature/index.txt rename to docs/nature/index.md diff --git a/docs/runner-mode.txt b/docs/runner-mode.md similarity index 100% rename from docs/runner-mode.txt rename to docs/runner-mode.md diff --git a/docs/terminal.txt b/docs/terminal.txt deleted file mode 100644 index 7683bbb..0000000 --- a/docs/terminal.txt +++ /dev/null @@ -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 - diff --git a/docs/timers.txt b/docs/timers.md similarity index 100% rename from docs/timers.txt rename to docs/timers.md diff --git a/docs/vim-mode/actions.txt b/docs/vim-mode/actions.md similarity index 100% rename from docs/vim-mode/actions.txt rename to docs/vim-mode/actions.md diff --git a/docs/vim-mode/index.txt b/docs/vim-mode/index.md similarity index 100% rename from docs/vim-mode/index.txt rename to docs/vim-mode/index.md diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index ca34425..3f0907e 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/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.`, ---- 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. +--- --- @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 diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 70e122c..8a6bf8c 100644 --- a/golibs/bait/bait.go +++ b/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 ( diff --git a/golibs/commander/commander.go b/golibs/commander/commander.go index 24f1c03..93785e2 100644 --- a/golibs/commander/commander.go +++ b/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 ( diff --git a/libs/lunacolors b/libs/lunacolors index 8467b87..cc271b6 160000 --- a/libs/lunacolors +++ b/libs/lunacolors @@ -1 +1 @@ -Subproject commit 8467b87dd8d49c68b4100b2d129d5f071544b8cf +Subproject commit cc271b6145e7cab91513cc7afdb0cc523e8878aa diff --git a/nature/commands/doc.lua b/nature/commands/doc.lua index a290cd8..bc16dfe 100644 --- a/nature/commands/doc.lua +++ b/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//.txt + -- dataDir/docs//.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 [[