Merge 2399c45960 into 8731b1a7d1

cmd/docgen/docgen.lua

@@ -1,6 +1,6 @@
 local fs = require 'fs'
 local emmyPattern = '^%-%-%- (.+)'
-local modpattern = '^%-+ @module (%w+)'
+local modpattern = '^%-+ @module (.+)'
 local pieces = {}
 
 local files = fs.readdir 'nature'
@@ -81,30 +81,70 @@ description: %s
 layout: doc
 menu:
   docs:
-    parent: "Nature"
+    parent: "%s"
 ---
 
 ]]
 
 for iface, dps in pairs(pieces) do
 	local mod = iface:match '(%w+)%.' or 'nature'
-	local path = string.format('docs/%s/%s.md', mod, iface)
+	local docParent = 'Nature'
+
+	path = string.format('docs/%s/%s.md', mod, iface)
+	if mod ~= 'nature' then
+		docParent = "API"
+		path = string.format('docs/api/%s/%s.md', mod, iface)
+	end
+
 	fs.mkdir(fs.dir(path), true)
-	local f <close> = io.open(path, 'w')
+
-	f:write(string.format(header, 'Module', iface, 'No description.'))
+	local exists = pcall(fs.stat, path)
+	local newOrNotNature = exists and mod ~= 'nature'
+
+	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))
+	end
 	print(f)
 
-	print(mod, path)
+	print('mod and path:', mod, path)
+
+	local tocSearch = false
+	local tocPos
+	for line in f:lines() do
+		if line:match '^## Functions' then
+			tocSearch = true
+		end
+		if tocSearch and line == '' then
+			tocSearch = false
+			tocPos = f:seek() - 1
+		end
+	end
 
 	for func, docs in pairs(dps) do
-		f:write(string.format('<hr>\n<div id=\'%s\'>', func))
 		local sig = string.format('%s.%s(', iface, func)
+		local params = ''
 		for idx, param in ipairs(docs.params) do
-			sig = sig .. ((param.name:gsub('%?$', '')))
+			sig = sig .. param.name:gsub('%?$', '')
-			if idx ~= #docs.params then sig = sig .. ', ' end
+			params = params .. param.name:gsub('%?$', '')
+			if idx ~= #docs.params then
+				sig = sig .. ', '
+				params = params .. ', '
+			end
 		end
 		sig = sig .. ')'
-		f:write(string.format([[			
+
+		if tocPos then
+			f:seek('set', tocPos)
+			local contents = f:read '*a'
+			f:seek('set', tocPos)
+			local tocLine = string.format('|<a href="#%s">%s</a>|%s|\n', func, string.format('%s(%s)', func, params), docs.description[1])
+			f:write(tocLine .. contents)
+			f:seek 'end'
+		end
+
+		f:write(string.format('<hr>\n<div id=\'%s\'>\n', func))
+		f:write(string.format([[
 <h4 class='heading'>
 %s
 <a href="#%s" class='heading-link'>

docs/api/hilbish/hilbish.messages.md

@@ -0,0 +1,107 @@
+---
+title: Module hilbish.messages
+description: No description.
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+<hr>
+<div id='all'>
+<h4 class='heading'>
+hilbish.messages.all()
+<a href="#all" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='clear'>
+<h4 class='heading'>
+hilbish.messages.clear()
+<a href="#clear" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='delete'>
+<h4 class='heading'>
+hilbish.messages.delete()
+<a href="#delete" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='read'>
+<h4 class='heading'>
+hilbish.messages.read()
+<a href="#read" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='send'>
+<h4 class='heading'>
+hilbish.messages.send(message)
+<a href="#send" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sends a message.
+#### Parameters
+`message` **`hilbish.message`**
+</div>
+
+<hr>
+<div id='readAll'>
+<h4 class='heading'>
+hilbish.messages.readAll()
+<a href="#readAll" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='unreadCount'>
+<h4 class='heading'>
+hilbish.messages.unreadCount()
+<a href="#unreadCount" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+

docs/api/hilbish/hilbish.runner.md

@@ -57,6 +57,12 @@ end)
 |<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
 |<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
 |<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.|
+|<a href="#exec">exec(cmd, runnerName)</a>|Executes cmd with a runner. If runnerName isn't passed, it uses|
+|<a href="#set">set(name, runner)</a>|Sets a runner by name. The runner table must have the run function in it.|
+|<a href="#get">get(name)</a>|Get a runner by name.|
+|<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners. If runner is a table,|
+|<a href="#setCurrent">setCurrent(name)</a>|Sets the current interactive/command line runner mode.|
+|<a href="#getCurrent">getCurrent()</a>|Returns the current runner by name.|
 
 <hr>
 <div id='runner.setMode'>
@@ -114,3 +120,92 @@ This is the equivalent of using `source`.
 
 </div>
 
+<hr>
+<div id='getCurrent'>
+<h4 class='heading'>
+hilbish.runner.getCurrent()
+<a href="#getCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns the current runner by name.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='setCurrent'>
+<h4 class='heading'>
+hilbish.runner.setCurrent(name)
+<a href="#setCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sets the current interactive/command line runner mode.
+#### Parameters
+`name` **`string`**
+</div>
+
+<hr>
+<div id='add'>
+<h4 class='heading'>
+hilbish.runner.add(name, runner)
+<a href="#add" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Adds a runner to the table of available runners. If runner is a table,
+it must have the run function in it.
+#### Parameters
+`name` **`string`**
+`runner` **`function`**
+</div>
+
+<hr>
+<div id='get'>
+<h4 class='heading'>
+hilbish.runner.get(name)
+<a href="#get" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Get a runner by name.
+#### Parameters
+`name` **`string`**
+</div>
+
+<hr>
+<div id='set'>
+<h4 class='heading'>
+hilbish.runner.set(name, runner)
+<a href="#set" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sets a runner by name. The runner table must have the run function in it.
+#### Parameters
+`name` **`string`**
+`runner` **`table`**
+</div>
+
+<hr>
+<div id='exec'>
+<h4 class='heading'>
+hilbish.runner.exec(cmd, runnerName)
+<a href="#exec" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Executes cmd with a runner. If runnerName isn't passed, it uses
+the user's current runner.
+#### Parameters
+`cmd` **`string`**
+`runnerName` **`string?`**
+</div>
+

docs/nature/dirs.md

@@ -8,7 +8,7 @@ menu:
 ---
 
 <hr>
-<div id='setOld'>			
+<div id='setOld'>
 <h4 class='heading'>
 dirs.setOld(d)
 <a href="#setOld" class='heading-link'>
@@ -22,7 +22,7 @@ Sets the old directory string.
 </div>
 
 <hr>
-<div id='push'>			
+<div id='push'>
 <h4 class='heading'>
 dirs.push()
 <a href="#push" class='heading-link'>
@@ -36,7 +36,7 @@ This function has no parameters.
 </div>
 
 <hr>
-<div id='peak'>			
+<div id='peak'>
 <h4 class='heading'>
 dirs.peak(num)
 <a href="#peak" class='heading-link'>
@@ -50,7 +50,7 @@ Look at `num` amount of recent directories, starting from the latest.
 </div>
 
 <hr>
-<div id='pop'>			
+<div id='pop'>
 <h4 class='heading'>
 dirs.pop(num)
 <a href="#pop" class='heading-link'>
@@ -64,7 +64,7 @@ Remove the specified amount of dirs from the recent directories list.
 </div>
 
 <hr>
-<div id='recent'>			
+<div id='recent'>
 <h4 class='heading'>
 dirs.recent(idx)
 <a href="#recent" class='heading-link'>

nature/hummingbird.lua

@@ -1,3 +1,4 @@
+-- @module hilbish.messages
 local bait = require 'bait'
 local commander = require 'commander'
 local lunacolors = require 'lunacolors'
@@ -46,7 +47,7 @@ end
 
 function hilbish.messages.read(idx)
 	local msg = M._messages[idx]
-	if msg then
+	if msg then 
 		M._messages[idx].read = true
 		unread = unread - 1
 	end

nature/runner.lua

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