docs: allow linking to types on different pages, improve docs for hilbish functions

docs-types
sammyette 2023-01-07 14:58:13 -04:00
parent a64f946055
commit 650b45b930
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
6 changed files with 42 additions and 31 deletions

23
api.go
View File

@ -231,8 +231,9 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext(t.Runtime, rt.IntValue(int64(exitcode)), rt.StringValue(stdoutStr), rt.StringValue(stderrStr)), nil return c.PushingNext(t.Runtime, rt.IntValue(int64(exitcode)), rt.StringValue(stdoutStr), rt.StringValue(stderrStr)), nil
} }
// cwd() // cwd() -> string
// Returns the current directory of the shell // Returns the current directory of the shell
// --- @returns string
func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
cwd, _ := os.Getwd() cwd, _ := os.Getwd()
@ -444,12 +445,12 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil return c.Next(), nil
} }
// timeout(cb, time) // timeout(cb, time) -> @Timer
// Runs the `cb` function after `time` in milliseconds // Runs the `cb` function after `time` in milliseconds.
// Returns a `timer` object (see `doc timers`). // This creates a timer that starts immediately.
// --- @param cb function // --- @param cb function
// --- @param time number // --- @param time number
// --- @returns table // --- @returns Timer
func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -470,12 +471,12 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext1(t.Runtime, rt.UserDataValue(timer.ud)), nil return c.PushingNext1(t.Runtime, rt.UserDataValue(timer.ud)), nil
} }
// interval(cb, time) // interval(cb, time) -> @Timer
// Runs the `cb` function every `time` milliseconds. // Runs the `cb` function every `time` milliseconds.
// Returns a `timer` object (see `doc timers`). // This creates a timer that starts immediately.
// --- @param cb function // --- @param cb function
// --- @param time number // --- @param time number
// --- @return table // --- @return Timer
func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -536,9 +537,11 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil return c.Next(), nil
} }
// which(name) // which(name) -> string
// Checks if `name` is a valid command // Checks if `name` is a valid command.
// Will return the path of the binary, or a basename if it's a commander.
// --- @param name string // --- @param name string
// --- @returns string
func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err

View File

@ -65,6 +65,7 @@ type tag struct {
var docs = make(map[string]module) var docs = make(map[string]module)
var interfaceDocs = make(map[string]module) var interfaceDocs = make(map[string]module)
var emmyDocs = make(map[string][]emmyPiece) var emmyDocs = make(map[string][]emmyPiece)
var typeTable = make(map[string][]string) // [0] = parentMod, [1] = interfaces
var prefix = map[string]string{ var prefix = map[string]string{
"main": "hl", "main": "hl",
"hilbish": "hl", "hilbish": "hl",
@ -183,6 +184,8 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
Properties: properties, Properties: properties,
} }
typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces}
return dps return dps
} }
@ -442,8 +445,9 @@ func main() {
// todo: get type from global table to link to // todo: get type from global table to link to
// other pages (hilbish page can link to hilbish.jobs#Job) // other pages (hilbish page can link to hilbish.jobs#Job)
typName := typ[1:] typName := typ[1:]
linkedTyp := strings.ToLower(typName) // TODO: link typLookup := typeTable[strings.ToLower(typName)]
return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName) linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName))
return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
}) })
f.WriteString(fmt.Sprintf("### %s\n", htmlSig)) f.WriteString(fmt.Sprintf("### %s\n", htmlSig))
for _, doc := range dps.Doc { for _, doc := range dps.Doc {

View File

@ -35,7 +35,7 @@ replacing <cmd> with the name of the command (for example `command.git`).
`cb` must be a function that returns a table of "completion groups." `cb` must be a function that returns a table of "completion groups."
Check `doc completions` for more information. Check `doc completions` for more information.
### cwd() ### cwd() -> string
Returns the current directory of the shell Returns the current directory of the shell
### exec(cmd) ### exec(cmd)
@ -60,9 +60,9 @@ override this function with your custom handler.
### inputMode(mode) ### inputMode(mode)
Sets the input mode for Hilbish's line reader. Accepts either emacs or vim Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
### interval(cb, time) ### interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
Runs the `cb` function every `time` milliseconds. Runs the `cb` function every `time` milliseconds.
Returns a `timer` object (see `doc timers`). This creates a timer that starts immediately.
### multiprompt(str) ### multiprompt(str)
Changes the continued line prompt to `str` Changes the continued line prompt to `str`
@ -95,10 +95,11 @@ 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 sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead. will call it to execute user input instead.
### timeout(cb, time) ### timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
Runs the `cb` function after `time` in milliseconds Runs the `cb` function after `time` in milliseconds.
Returns a `timer` object (see `doc timers`). This creates a timer that starts immediately.
### which(name) ### which(name) -> string
Checks if `name` is a valid command Checks if `name` is a valid command.
Will return the path of the binary, or a basename if it's a commander.

View File

@ -21,16 +21,16 @@ Stops the job from running.
### add(cmdstr, args, execPath) ### add(cmdstr, args, execPath)
Adds a new job to the job table. Note that this does not immediately run it. Adds a new job to the job table. Note that this does not immediately run it.
### all() -> table\<<a href="#job" style="text-decoration: none;">Job</a>> ### all() -> table\<<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;">Job</a>>
Returns a table of all job objects. Returns a table of all job objects.
### disown(id) ### disown(id)
Disowns a job. This deletes it from the job table. Disowns a job. This deletes it from the job table.
### get(id) -> <a href="#job" style="text-decoration: none;">Job</a> ### get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;">Job</a>
Get a job object via its ID. Get a job object via its ID.
### last() -> <a href="#job" style="text-decoration: none;">Job</a> ### last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;">Job</a>
Returns the last added job from the table. Returns the last added job from the table.
## Types ## Types

View File

@ -35,11 +35,11 @@ print(t.running) // true
- `TIMEOUT`: Constant for a timeout timer type - `TIMEOUT`: Constant for a timeout timer type
## Functions ## Functions
### create(type, time, callback) -> <a href="#timer" style="text-decoration: none;">Timer</a> ### create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
Creates a timer that runs based on the specified `time` in milliseconds. Creates a timer that runs based on the specified `time` in milliseconds.
The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
### get(id) -> <a href="#timer" style="text-decoration: none;">Timer</a> ### get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
Retrieves a timer via its ID. Retrieves a timer via its ID.
## Types ## Types

View File

@ -63,6 +63,7 @@ function hilbish.appendPath(dir) end
function hilbish.complete(scope, cb) end function hilbish.complete(scope, cb) end
--- Returns the current directory of the shell --- Returns the current directory of the shell
--- @returns string
function hilbish.cwd() end function hilbish.cwd() end
--- Replaces running hilbish with `cmd` --- Replaces running hilbish with `cmd`
@ -94,10 +95,10 @@ function hilbish.hinter(line, pos) end
function hilbish.inputMode(mode) end function hilbish.inputMode(mode) end
--- Runs the `cb` function every `time` milliseconds. --- Runs the `cb` function every `time` milliseconds.
--- Returns a `timer` object (see `doc timers`). --- This creates a timer that starts immediately.
--- @param cb function --- @param cb function
--- @param time number --- @param time number
--- @return table --- @return Timer
function hilbish.interval(cb, time) end function hilbish.interval(cb, time) end
--- Changes the continued line prompt to `str` --- Changes the continued line prompt to `str`
@ -141,15 +142,17 @@ function hilbish.run(cmd, returnOut) end
--- @param mode string|function --- @param mode string|function
function hilbish.runnerMode(mode) end function hilbish.runnerMode(mode) end
--- Runs the `cb` function after `time` in milliseconds --- Runs the `cb` function after `time` in milliseconds.
--- Returns a `timer` object (see `doc timers`). --- This creates a timer that starts immediately.
--- @param cb function --- @param cb function
--- @param time number --- @param time number
--- @returns table --- @returns Timer
function hilbish.timeout(cb, time) end function hilbish.timeout(cb, time) end
--- Checks if `name` is a valid command --- Checks if `name` is a valid command.
--- Will return the path of the binary, or a basename if it's a commander.
--- @param name string --- @param name string
--- @returns string
function hilbish.which(name) end function hilbish.which(name) end
--- Puts a job in the background. This acts the same as initially running a job. --- Puts a job in the background. This acts the same as initially running a job.