docs: add back hilbish.jobs doc

cmd/docgen/docgen.go

@@ -299,7 +299,25 @@ start:
 func main() {
 	fset := token.NewFileSet()
 	os.Mkdir("docs", 0777)
+	os.RemoveAll("docs/api")
 	os.Mkdir("docs/api", 0777)
+
+	f, err := os.Create("docs/api/_index.md")
+	if err != nil {
+		panic(err)
+	}
+	f.WriteString(`---
+title: API
+layout: doc
+weight: -100
+menu: docs
+---
+
+Welcome to the API documentation for Hilbish. This documents Lua functions
+provided by Hilbish.
+`)
+	f.Close()
+
 	os.Mkdir("emmyLuaDocs", 0777)
 
 	dirs := []string{"./"}

cmd/docgen/docgen.lua

@@ -1,7 +1,9 @@
 local fs = require 'fs'
 local emmyPattern = '^%-%-%- (.+)'
+local emmyPattern2 = '^%-%- (.+)'
 local modpattern = '^%-+ @module (.+)'
 local pieces = {}
+local descriptions = {}
 
 local files = fs.readdir 'nature'
 for _, fname in ipairs(files) do
@@ -15,16 +17,24 @@ for _, fname in ipairs(files) do
 
 	print(fname, mod)
 	pieces[mod] = {}
+	descriptions[mod] = {}
 
 	local docPiece = {}
 	local lines = {}
 	local lineno = 0
+	local doingDescription = true
+
 	for line in f:lines() do
 		lineno = lineno + 1
 		lines[lineno] = line
 
 		if line == header then goto continue2 end
-		if not line:match(emmyPattern) then
+		if line:match(emmyPattern) or line:match(emmyPattern2) then
+			if doingDescription then
+				table.insert(descriptions[mod], line:match(emmyPattern) or line:match(emmyPattern2))
+			end
+		else
+			doingDescription = false
 			if line:match '^function' then
 				local pattern = (string.format('^function %s%%.', mod) .. '(%w+)')
 				local funcName = line:match(pattern)
@@ -107,7 +117,12 @@ for iface, dps in pairs(pieces) do
 
 	local f <close> = io.open(path, newOrNotNature and 'r+' or 'w+')
 	if not newOrNotNature then
-		f:write(string.format(header, 'Module', iface, 'No description.', docParent))
+		f:write(string.format(header, 'Module', iface, (descriptions[iface] and #descriptions[iface] > 0) and descriptions[iface][1] or 'No description.', docParent))
+		if descriptions[iface] and #descriptions[iface] > 0 then
+			table.remove(descriptions[iface], 1)
+			f:write(string.format('\n## Introduction\n%s\n\n', table.concat(descriptions[iface], '\n')))
+			f:write('## Functions\n')
+		end
 	end
 	print(f)
 

docs/nature/dirs.md

@@ -1,12 +1,18 @@
 ---
 title: Module dirs
-description: No description.
+description: internal directory management
 layout: doc
 menu:
   docs:
     parent: "Nature"
 ---
 
+
+## Introduction
+The dirs module defines a small set of functions to store and manage
+directories.
+
+## Functions
 <hr>
 <div id='setOld'>
 <h4 class='heading'>

docs/nature/doc.md

@@ -1,12 +1,20 @@
 ---
 title: Module doc
-description: No description.
+description: command-line doc rendering
 layout: doc
 menu:
   docs:
     parent: "Nature"
 ---
 
+
+## Introduction
+The doc module contains a small set of functions
+used by the Greenhouse pager to render parts of the documentation pages.
+This is only documented for the sake of it. It's only intended use
+is by the Greenhouse pager.
+
+## Functions
 <hr>
 <div id='renderInfoBlock'>
 <h4 class='heading'>