.github/workflows/docs.yml

@@ -4,15 +4,24 @@ on:
   push:
     branches:
       - master
+      - docs-refactor
 
 jobs:
   gen:
     runs-on: ubuntu-latest
     steps:
       - 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:

api.go

@@ -1,14 +1,6 @@
 // the core Hilbish API
 // The Hilbish module includes the core API, containing
 // interfaces and functions which directly relate to shell functionality.
-// #field ver The version of Hilbish
-// #field user Username of the user
-// #field host Hostname of the machine
-// #field dataDir Directory for Hilbish data files, including the docs and default modules
-// #field interactive Is Hilbish in an interactive shell?
-// #field login Is Hilbish the login shell?
-// #field vimMode Current Vim input mode of Hilbish (will be nil if not in Vim input mode)
-// #field exitCode xit code of the last executed command
 package main
 
 import (

cmd/docgen/docgen.go

@@ -70,11 +70,16 @@ var prefix = map[string]string{
 	"terminal": "term",
 }
 
-func getTagsAndDocs(docs string) (map[string][]tag, []string) {
+func setupDoc(mod string, fun *doc.Func) *docPiece {
+	docs := strings.TrimSpace(fun.Doc)
+	inInterface := strings.HasPrefix(docs, "#interface")
+	if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) {
+		return nil
+	}
+
 	pts := strings.Split(docs, "\n")
 	parts := []string{}
 	tags := make(map[string][]tag)
-
 	for _, part := range pts {
 		if strings.HasPrefix(part, "#") {
 			tagParts := strings.Split(strings.TrimPrefix(part, "#"), " ")
@@ -104,30 +109,6 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) {
 		}
 	}
 
-	return tags, parts
-}
-
-func docPieceTag(tagName string, tags map[string][]tag) []docPiece {
-	dps := []docPiece{}
-	for _, tag := range tags[tagName] {
-		dps = append(dps, docPiece{
-			FuncName: tag.id,
-			Doc: tag.fields,
-		})
-	}
-
-	return dps
-}
-
-func setupDoc(mod string, fun *doc.Func) *docPiece {
-	docs := strings.TrimSpace(fun.Doc)
-	inInterface := strings.HasPrefix(docs, "#interface")
-	if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) {
-		return nil
-	}
-
-	tags, parts := getTagsAndDocs(docs)
-
 	var interfaces string
 	funcsig := parts[0]
 	doc := parts[1:]
@@ -140,8 +121,22 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 	}
 	em := emmyPiece{FuncName: funcName}
 
-	fields := docPieceTag("field", tags)
+	// manage fields
-	properties := docPieceTag("property", tags)
+	fields := []docPiece{}
+	for _, tag := range tags["field"] {
+		fields = append(fields, docPiece{
+			FuncName: tag.id,
+			Doc: tag.fields,
+		})
+	}
+
+	properties := []docPiece{}
+	for _, tag := range tags["property"] {
+		properties = append(properties, docPiece{
+			FuncName: tag.id,
+			Doc: tag.fields,
+		})
+	}
 
 	for _, d := range doc {
 		if strings.HasPrefix(d, "---") {
@@ -250,7 +245,7 @@ func main() {
 			}
 		}
 
-		tags, descParts := getTagsAndDocs(strings.TrimSpace(p.Doc))
+		descParts := strings.Split(strings.TrimSpace(p.Doc), "\n")
 		shortDesc := descParts[0]
 		desc := descParts[1:]
 		filteredPieces := []docPiece{}
@@ -284,8 +279,6 @@ func main() {
 			ShortDescription: shortDesc,
 			Description: strings.Join(desc, "\n"),
 			HasInterfaces: hasInterfaces,
-			Properties: docPieceTag("property", tags),
-			Fields: docPieceTag("field", tags),
 		}
 	}
 

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/hilbish/_index.md

@@ -11,16 +11,6 @@ menu:
 The Hilbish module includes the core API, containing
 interfaces and functions which directly relate to shell functionality.
 
-## Interface fields
-- `ver`: The version of Hilbish
-- `user`: Username of the user
-- `host`: Hostname of the machine
-- `dataDir`: Directory for Hilbish data files, including the docs and default modules
-- `interactive`: Is Hilbish in an interactive shell?
-- `login`: Is Hilbish the login shell?
-- `vimMode`: Current Vim input mode of Hilbish (will be nil if not in Vim input mode)
-- `exitCode`: xit code of the last executed command
-
 ## Functions
 ### alias(cmd, orig)
 Sets an alias of `cmd` to `orig`