chore: merge

.github/workflows/docs.yml

@@ -2,16 +2,26 @@ name: Generate docs
 
 on:
   push:
-    branches: [master]
+    branches:
+      - master
+      - docs-refactor
 
 jobs:
   gen:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
       - uses: actions/setup-go@v2
+      - name: Download Task
+        run: 'sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d'
+      - name: Build
+        run: ./bin/task
       - name: Run docgen
         run: go run cmd/docgen/docgen.go
+      - name: Run lua docgen
+        run: ./hilbish cmd/docgen/docgen.lua
       - name: Commit new docs
         uses: stefanzweifel/git-auto-commit-action@v4
         with:

.gitignore

@@ -2,6 +2,7 @@
 hilbish
 !docs/api/hilbish
 docgen
+!cmd/docgen
 
 .vim
 petals/

cmd/docgen/docgen.go

@@ -13,9 +13,12 @@ import (
 )
 
 var header = `---
-name: %s %s
+title: %s %s
 description: %s
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 `

cmd/docgen/docgen.lua

@@ -0,0 +1,70 @@
+local fs = require 'fs'
+local emmyPattern = '^%-%-%- (.+)'
+local pieces = {}
+
+local files = fs.readdir 'nature'
+for _, fname in ipairs(files) do
+	local isScript = fname:match'%.lua$'
+	if not isScript then goto continue end
+
+	local f = io.open(string.format('nature/%s', fname))
+	local header = f:read '*l'
+	if not header:match(emmyPattern) then goto continue end
+
+	print(fname)
+
+	local iface = header:match(emmyPattern)
+	pieces[iface] = {}
+
+	local docPiece = {}
+	for line in f:lines() do
+		if line == header then goto continue2 end
+		if not line:match(emmyPattern) then
+			if line:match '^function' then
+				local pattern = (string.format('^function %s.', iface) .. '(%w+)')
+				local funcName = line:match(pattern)
+				pieces[iface][funcName] = docPiece
+			end
+			docPiece = {}
+			goto continue2
+		end
+
+		table.insert(docPiece, line)
+		::continue2::
+	end
+	::continue::
+end
+
+for iface, dps in pairs(pieces) do
+	local mod = iface:match '(%w+)%.'
+	local path = string.format('docs/api/%s/%s.md', mod, iface)
+	local f <close> = io.open(path, 'a+')
+
+	print(mod, path)
+
+	for func, docs in pairs(dps) do
+		local params = table.filter(docs, function(t)
+			return t:match '^%-%-%- @param'
+		end)
+		f:write(string.format('## %s(', func))
+		for i, str in ipairs(params) do
+			if i ~= 1 then
+				f:write ', '
+			end
+			f:write(str:match '^%-%-%- @param ([%w]+) ')
+		end
+		f:write(')\n')
+
+		for _, str in ipairs(docs) do
+			if not str:match '^%-%-%- @' then
+				f:write(str:match '^%-%-%- (.+)' .. '\n')
+			end	
+		end
+		f:write('\n')
+	end
+	f:flush()
+end
+
+
+
+

docs/api/_index.md

@@ -0,0 +1,7 @@
+---
+title: API
+layout: doc
+weight: -50
+menu: docs
+---
+

docs/api/bait.md

@@ -1,7 +1,10 @@
 ---
-name: Module bait
+title: Module bait
 description: the event emitter
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/commander.md

@@ -1,7 +1,10 @@
 ---
-name: Module commander
+title: Module commander
 description: library for custom commands
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/fs.md

@@ -1,7 +1,10 @@
 ---
-name: Module fs
+title: Module fs
 description: filesystem interaction and functionality library
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/_index.md

@@ -1,7 +1,10 @@
 ---
-name: Module hilbish
+title: Module hilbish
 description: the core Hilbish API
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/hilbish.aliases.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.aliases
+title: Interface hilbish.aliases
 description: command aliasing
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/hilbish.completions.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.completions
+title: Interface hilbish.completions
 description: tab completions
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/hilbish.editor.md

@@ -0,0 +1,26 @@
+---
+title: Interface hilbish.editor
+description: interactions for Hilbish's line reader
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+## Introduction
+The hilbish.editor interface provides functions to
+directly interact with the line editor in use.
+
+## Functions
+### getLine()
+Returns the current input line.
+
+### getVimRegister(register)
+Returns the text that is at the register.
+
+### insert(text)
+Inserts text into the line.
+
+### setVimRegister(register, text)
+Sets the vim register at `register` to hold the passed text.
+

docs/api/hilbish/hilbish.history.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.history
+title: Interface hilbish.history
 description: command history
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/hilbish.jobs.md

@@ -1,11 +1,15 @@
 ---
-name: Interface hilbish.jobs
+title: Interface hilbish.jobs
 description: background job management
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction
- Manage interactive jobs in Hilbish via Lua.
+
+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.

docs/api/hilbish/hilbish.os.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.os
+title: Interface hilbish.os
 description: OS Info
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/hilbish.runner.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.runner
+title: Interface hilbish.runner
 description: interactive command runner customization
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/hilbish/hilbish.timers.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.timers
+title: Interface hilbish.timers
 description: timeout and interval API
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction
@@ -9,7 +12,22 @@ The timers interface si one to easily set timeouts and intervals
 to run functions after a certain time or repeatedly without using
 odd tricks.
 
+## 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
+
 ## Functions
+### start()
+Starts a timer.
+
 ### stop()
 Stops a timer.
 
+### create(type, time, callback)
+Creates a timer that runs based on the specified `time` in milliseconds.
+The `type` can either be interval (value of 0) or timeout (value of 1).
+
+### get(id)
+Retrieves a timer via its ID.
+

docs/api/hilbish/hilbish.userDir.md

@@ -1,7 +1,10 @@
 ---
-name: Interface hilbish.userDir
+title: Interface hilbish.userDir
 description: user-related directories
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

docs/api/terminal.md

@@ -1,7 +1,10 @@
 ---
-name: Module terminal
+title: Module terminal
 description: low level terminal library
-layout: apidoc
+layout: doc
+menu:
+  docs:
+    parent: "API"
 ---
 
 ## Introduction

editor.go

@@ -6,6 +6,10 @@ import (
 	rt "github.com/arnodel/golua/runtime"
 )
 
+// #interface editor
+// interactions for Hilbish's line reader
+// The hilbish.editor interface provides functions to
+// directly interact with the line editor in use.
 func editorLoader(rtm *rt.Runtime) *rt.Table {
 	exports := map[string]util.LuaExport{
 		"insert": {editorInsert, 1, false},
@@ -20,6 +24,9 @@ func editorLoader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
+// #interface editor
+// insert(text)
+// Inserts text into the line.
 func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -35,6 +42,9 @@ func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface editor
+// setVimRegister(register, text)
+// Sets the vim register at `register` to hold the passed text.
 func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -55,6 +65,9 @@ func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface editor
+// getVimRegister(register)
+// Returns the text that is at the register.
 func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -70,6 +83,9 @@ func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.StringValue(string(buf))), nil
 }
 
+// #interface editor
+// getLine()
+// Returns the current input line.
 func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	buf := lr.rl.GetLine()
 

emmyLuaDocs/hilbish.lua

@@ -22,6 +22,18 @@ function hilbish.completions.call(name, query, ctx, fields) end
 --- You can check the completions doc for more info.
 function hilbish.completions.handler(line, pos) end
 
+--- Returns the current input line.
+function hilbish.editor.getLine() end
+
+--- Returns the text that is at the register.
+function hilbish.editor.getVimRegister(register) end
+
+--- Inserts text into the line.
+function hilbish.editor.insert(text) end
+
+--- Sets the vim register at `register` to hold the passed text.
+function hilbish.editor.setVimRegister(register, text) end
+
 --- Sets an alias of `cmd` to `orig`
 --- @param cmd string
 --- @param orig string
@@ -155,6 +167,9 @@ function hilbish.jobs.stop() end
 --- This is the equivalent of using `source`.
 function hilbish.runner.sh(cmd) end
 
+--- Starts a timer.
+function hilbish.timers:start() end
+
 --- Stops a timer.
 function hilbish.timers:stop() end
 
@@ -199,4 +214,11 @@ function hilbish.history.get(idx) end
 --- @returns number
 function hilbish.history.size() end
 
+--- Creates a timer that runs based on the specified `time` in milliseconds.
+--- The `type` can either be interval (value of 0) or timeout (value of 1).
+function hilbish.timers.create(type, time, callback) end
+
+--- Retrieves a timer via its ID.
+function hilbish.timers.get(id) end
+
 return hilbish

nature/runner.lua

@@ -1,3 +1,4 @@
+--- hilbish.runner
 local currentRunner = 'hybrid'
 local runners = {}
 

timer.go

@@ -73,6 +73,10 @@ func (t *timer) stop() error {
 	return nil
 }
 
+// #interface timers
+// #member
+// start()
+// Starts a timer.
 func timerStart(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err

timerhandler.go

@@ -61,6 +61,10 @@ func (th *timersModule) get(id int) *timer {
 	return th.timers[id]
 }
 
+// #interface timers
+// create(type, time, callback)
+// Creates a timer that runs based on the specified `time` in milliseconds.
+// The `type` can either be interval (value of 0) or timeout (value of 1).
 func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(3); err != nil {
 		return nil, err
@@ -83,6 +87,9 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.UserDataValue(tmr.ud)), nil
 }
 
+// #interface timers
+// get(id)
+// Retrieves a timer via its ID.
 func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -101,6 +108,9 @@ func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface timers
+// #property type What type of timer it is
+// #property running If the timer is running
+// #property duration The duration in milliseconds that the timer will run
 // timeout and interval API
 // The timers interface si one to easily set timeouts and intervals
 // to run functions after a certain time or repeatedly without using

website/content/docs/api

@@ -0,0 +1 @@
+../../../docs/api/