fix: list subdocs for hilbish module

- get docs properly for hilbish module and its interfaces
- deal with negative numbers causing yaml metadata parsing to fail
- change from index to _index to match hugo

api.go

@@ -109,70 +109,59 @@ func hilbishLoad(rtm *rt.Runtime) (rt.Value, func()) {
 		username = strings.Split(username, "\\")[1] // for some reason Username includes the hostname on windows
 	}
 
-	util.SetFieldProtected(fakeMod, mod, "ver", rt.StringValue(getVersion()), "Hilbish version")
+	util.SetFieldProtected(fakeMod, mod, "ver", rt.StringValue(getVersion()))
-	util.SetFieldProtected(fakeMod, mod, "user", rt.StringValue(username), "Username of user")
+	util.SetFieldProtected(fakeMod, mod, "user", rt.StringValue(username))
-	util.SetFieldProtected(fakeMod, mod, "host", rt.StringValue(host), "Host name of the machine")
+	util.SetFieldProtected(fakeMod, mod, "host", rt.StringValue(host))
-	util.SetFieldProtected(fakeMod, mod, "home", rt.StringValue(curuser.HomeDir), "Home directory of the user")
+	util.SetFieldProtected(fakeMod, mod, "home", rt.StringValue(curuser.HomeDir))
-	util.SetFieldProtected(fakeMod, mod, "dataDir", rt.StringValue(dataDir), "Directory for Hilbish's data files")
+	util.SetFieldProtected(fakeMod, mod, "dataDir", rt.StringValue(dataDir))
-	util.SetFieldProtected(fakeMod, mod, "interactive", rt.BoolValue(interactive), "If this is an interactive shell")
+	util.SetFieldProtected(fakeMod, mod, "interactive", rt.BoolValue(interactive))
-	util.SetFieldProtected(fakeMod, mod, "login", rt.BoolValue(login), "Whether this is a login shell")
+	util.SetFieldProtected(fakeMod, mod, "login", rt.BoolValue(login))
-	util.SetFieldProtected(fakeMod, mod, "vimMode", rt.NilValue, "Current Vim mode of Hilbish (nil if not in Vim mode)")
+	util.SetFieldProtected(fakeMod, mod, "vimMode", rt.NilValue)
-	util.SetFieldProtected(fakeMod, mod, "exitCode", rt.IntValue(0), "Exit code of last exected command")
+	util.SetFieldProtected(fakeMod, mod, "exitCode", rt.IntValue(0))
-	util.Document(fakeMod, "Hilbish's core API, containing submodules and functions which relate to the shell itself.")
 
 	// hilbish.userDir table
 	hshuser := userDirLoader(rtm)
-	util.Document(hshuser, "User directories to store configs and/or modules.")
 	mod.Set(rt.StringValue("userDir"), rt.TableValue(hshuser))
 
 	// hilbish.os table
 	hshos := hshosLoader(rtm)
-	util.Document(hshos, "OS info interface")
 	mod.Set(rt.StringValue("os"), rt.TableValue(hshos))
 
 	// hilbish.aliases table
 	aliases = newAliases()
 	aliasesModule := aliases.Loader(rtm)
-	util.Document(aliasesModule, "Alias inferface for Hilbish.")
 	mod.Set(rt.StringValue("aliases"), rt.TableValue(aliasesModule))
 
 	// hilbish.history table
 	historyModule := lr.Loader(rtm)
 	mod.Set(rt.StringValue("history"), rt.TableValue(historyModule))
-	util.Document(historyModule, "History interface for Hilbish.")
 
 	// hilbish.completion table
 	hshcomp := completionLoader(rtm)
-	util.Document(hshcomp, "Completions interface for Hilbish.")
 	mod.Set(rt.StringValue("completion"), rt.TableValue(hshcomp))
 
 	// hilbish.runner table
 	runnerModule := runnerModeLoader(rtm)
-	util.Document(runnerModule, "Runner/exec interface for Hilbish.")
 	mod.Set(rt.StringValue("runner"), rt.TableValue(runnerModule))
 
 	// hilbish.jobs table
 	jobs = newJobHandler()
 	jobModule := jobs.loader(rtm)
-	util.Document(jobModule, "(Background) job interface.")
 	mod.Set(rt.StringValue("jobs"), rt.TableValue(jobModule))
 
 	// hilbish.timers table
 	timers = newTimersModule()
 	timersModule := timers.loader(rtm)
-	util.Document(timersModule, "Timer interface, for control of all intervals and timeouts.")
 	mod.Set(rt.StringValue("timers"), rt.TableValue(timersModule))
 
 	editorModule := editorLoader(rtm)
-	util.Document(editorModule, "")
 	mod.Set(rt.StringValue("editor"), rt.TableValue(editorModule))
 
 	versionModule := rt.NewTable()
-	util.SetField(rtm, versionModule, "branch", rt.StringValue(gitBranch), "Git branch Hilbish was compiled from")
+	util.SetField(rtm, versionModule, "branch", rt.StringValue(gitBranch))
-	util.SetField(rtm, versionModule, "full", rt.StringValue(getVersion()), "Full version info, including release name")
+	util.SetField(rtm, versionModule, "full", rt.StringValue(getVersion()))
-	util.SetField(rtm, versionModule, "commit", rt.StringValue(gitCommit), "Git commit Hilbish was compiled from")
+	util.SetField(rtm, versionModule, "commit", rt.StringValue(gitCommit))
-	util.SetField(rtm, versionModule, "release", rt.StringValue(releaseName), "Release name")
+	util.SetField(rtm, versionModule, "release", rt.StringValue(releaseName))
-	util.Document(versionModule, "Version info interface.")
 	mod.Set(rt.StringValue("version"), rt.TableValue(versionModule))
 
 	return rt.TableValue(fakeMod), nil
@@ -187,12 +176,12 @@ func getenv(key, fallback string) string {
 }
 
 func setVimMode(mode string) {
-	util.SetField(l, hshMod, "vimMode", rt.StringValue(mode), "Current Vim mode of Hilbish (nil if not in Vim mode)")
+	util.SetField(l, hshMod, "vimMode", rt.StringValue(mode))
 	hooks.Emit("hilbish.vimMode", mode)
 }
 
 func unsetVimMode() {
-	util.SetField(l, hshMod, "vimMode", rt.NilValue, "Current Vim mode of Hilbish (nil if not in Vim mode)")
+	util.SetField(l, hshMod, "vimMode", rt.NilValue)
 }
 
 // run(cmd, returnOut) -> exitCode, stdout, stderr

docs/api/_index.md

@@ -5,3 +5,4 @@ weight: -50
 menu: docs
 ---
 
+Hello!

docs/api/index.md

@@ -0,0 +1 @@
+hello!

exec.go

@@ -552,7 +552,7 @@ func splitInput(input string) ([]string, string) {
 }
 
 func cmdFinish(code uint8, cmdstr string, private bool) {
-	util.SetField(l, hshMod, "exitCode", rt.IntValue(int64(code)), "Exit code of last exected command")
+	util.SetField(l, hshMod, "exitCode", rt.IntValue(int64(code)))
 	// using AsValue (to convert to lua type) on an interface which is an int
 	// results in it being unknown in lua .... ????
 	// so we allow the hook handler to take lua runtime Values

golibs/bait/bait.go

@@ -204,15 +204,6 @@ func (b *Bait) loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	mod := rt.NewTable()
 	util.SetExports(rtm, mod, exports)
 
-	util.Document(mod,
-`Bait is the event emitter for Hilbish. Why name it bait?
-Because it throws hooks that you can catch (emits events
-that you can listen to) and because why not, fun naming
-is fun. 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, see doc hooks.`)
-
 	return rt.TableValue(mod), nil
 }
 

golibs/commander/commander.go

@@ -34,7 +34,6 @@ func (c *Commander) loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	}
 	mod := rt.NewTable()
 	util.SetExports(rtm, mod, exports)
-	util.Document(mod, "Commander is Hilbish's custom command library, a way to write commands in Lua.")
 
 	return rt.TableValue(mod), nil
 }

golibs/fs/fs.go

@@ -39,10 +39,6 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	mod.Set(rt.StringValue("pathSep"), rt.StringValue(string(os.PathSeparator)))
 	mod.Set(rt.StringValue("pathListSep"), rt.StringValue(string(os.PathListSeparator)))
 
-	util.Document(mod, `The fs module provides easy and simple access to
-filesystem functions and other things, and acts an
-addition to the Lua standard library's I/O and filesystem functions.`)
-
 	return rt.TableValue(mod), nil
 }
 

golibs/terminal/terminal.go

@@ -28,7 +28,6 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 
 	mod := rt.NewTable()
 	util.SetExports(rtm, mod, exports)
-	util.Document(mod, "The terminal library is a simple and lower level library for certain terminal interactions.")
 
 	return rt.TableValue(mod), nil
 }

nature/commands/doc.lua

@@ -15,32 +15,34 @@ commander.register('doc', function(args)
 
 		local f = io.open(moddocPath .. mod .. '.md', 'rb')
 		local funcdocs = nil
+		local subdocName = args[2]
 		if not f then
 			-- assume subdir
 			-- dataDir/docs/<mod>/<mod>.md
 			moddocPath = moddocPath .. mod .. '/'
-			local subdocName = args[2]
 			if not subdocName then
-				subdocName = 'index'
+				subdocName = '_index'
 			end
 			f = io.open(moddocPath .. subdocName .. '.md', 'rb')
+			if not f then
+				moddocPath = moddocPath .. subdocName .. '/'
+				subdocName = args[3] or '_index'
+				f = io.open(moddocPath .. subdocName .. '.md', 'rb')
+			end
 			if not f then
 				print('No documentation found for ' .. mod .. '.')
 				return
 			end
-			funcdocs = f:read '*a'
+		end
-			local moddocs = table.filter(fs.readdir(moddocPath), function(f) return f ~= 'index.md' end)
+		funcdocs = f:read '*a':gsub('-([%d]+)', '%1')
+		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, '.md', '')))
 		end)
-			if subdocName == 'index' then
+		if subdocName == '_index' then
 			funcdocs = funcdocs .. '\nSubdocs: ' .. table.concat(subdocs, ', ')
 		end
-		end
 
-		if not funcdocs then
-			funcdocs = f:read '*a'
-		end
 		local valsStr = funcdocs:match '%-%-%-\n([^%-%-%-]+)\n'
 		local vals = {}
 		if valsStr then
@@ -53,11 +55,13 @@ commander.register('doc', function(args)
 				local key = line:match '(%w+): '
 				local val = line:match '^%w+: (.-)$'
 
+				if key then
 					vals[key] = val
 				end
 			end
+		end
 		if mod == 'api' then
-			funcdocs = string.format(apidocHeader, vals.name, vals.description) .. funcdocs
+			funcdocs = string.format(apidocHeader, vals.title, vals.description or 'no description.') .. funcdocs
 		end
 		local backtickOccurence = 0
 		local formattedFuncs = lunacolors.format(funcdocs:sub(1, #funcdocs - 1):gsub('`', function()

os.go

@@ -19,9 +19,9 @@ func hshosLoader(rtm *rt.Runtime) *rt.Table {
 	info, _ := osinfo.GetOSInfo()
 	mod := rt.NewTable()
 
-	util.SetField(rtm, mod, "family", rt.StringValue(info.Family), "Family name of the current OS")
+	util.SetField(rtm, mod, "family", rt.StringValue(info.Family))
-	util.SetField(rtm, mod, "name", rt.StringValue(info.Name), "Pretty name of the current OS")
+	util.SetField(rtm, mod, "name", rt.StringValue(info.Name))
-	util.SetField(rtm, mod, "version", rt.StringValue(info.Version), "Version of the current OS")
+	util.SetField(rtm, mod, "version", rt.StringValue(info.Version))
 
 	return mod
 }

userdir.go

@@ -16,8 +16,8 @@ import (
 func userDirLoader(rtm *rt.Runtime) *rt.Table {
 	mod := rt.NewTable()
 
-	util.SetField(rtm, mod, "config", rt.StringValue(confDir), "User's config directory")
+	util.SetField(rtm, mod, "config", rt.StringValue(confDir))
-	util.SetField(rtm, mod, "data", rt.StringValue(userDataDir), "XDG data directory")
+	util.SetField(rtm, mod, "data", rt.StringValue(userDataDir))
 
 	return mod
 }

util/util.go

@@ -10,53 +10,18 @@ import (
 	rt "github.com/arnodel/golua/runtime"
 )
 
-// Document adds a documentation string to a module.
-// It is accessible via the __doc metatable.
-func Document(module *rt.Table, doc string) {
-	mt := module.Metatable()
-	
-	if mt == nil {
-		mt = rt.NewTable()
-		module.SetMetatable(mt)
-	}
-
-	mt.Set(rt.StringValue("__doc"), rt.StringValue(doc))
-}
-
 // SetField sets a field in a table, adding docs for it.
 // It is accessible via the __docProp metatable. It is a table of the names of the fields.
-func SetField(rtm *rt.Runtime, module *rt.Table, field string, value rt.Value, doc string) {
+func SetField(rtm *rt.Runtime, module *rt.Table, field string, value rt.Value) {
 	// TODO:    ^ rtm isnt needed, i should remove it
-	SetFieldDoc(module, field, doc)
 	module.Set(rt.StringValue(field), value)
 }
 
-// SetFieldDoc sets the __docProp metatable for a field on the
-// module.
-func SetFieldDoc(module *rt.Table, field, doc string) {
-	mt := module.Metatable()
-
-	if mt == nil {
-		mt = rt.NewTable()
-		module.SetMetatable(mt)
-	}
-
-	docProp := mt.Get(rt.StringValue("__docProp"))
-	if docProp == rt.NilValue {
-		docPropTbl := rt.NewTable()
-		mt.Set(rt.StringValue("__docProp"), rt.TableValue(docPropTbl))
-		docProp = mt.Get(rt.StringValue("__docProp"))
-	}
-
-	docProp.AsTable().Set(rt.StringValue(field), rt.StringValue(doc))
-}
-
 // SetFieldProtected sets a field in a protected table. A protected table
 // is one which has a metatable proxy to ensure no overrides happen to it.
 // It sets the field in the table and sets the __docProp metatable on the
 // user facing table.
-func SetFieldProtected(module, realModule *rt.Table, field string, value rt.Value, doc string) {
+func SetFieldProtected(module, realModule *rt.Table, field string, value rt.Value) {
-	SetFieldDoc(module, field, doc)
 	realModule.Set(rt.StringValue(field), value)
 }