Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: make lua implemented hilbish interfaces documented #335

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

fix: make lua implemented hilbish interfaces documented #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b1e074c
fix: make lua implemented hilbish interfaces documented
TorchedSammy Dec 24, 2024
5545002
fix: signature link in table of contents
TorchedSammy Dec 24, 2024
b7af617
fix: reduce function list to match in go generated docs
TorchedSammy Dec 24, 2024
5af9aa2
fix: toc appending
TorchedSammy Jan 12, 2025
2399c45
docs: enable docs for hilbish.messages
TorchedSammy Jan 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 50 additions & 10 deletions cmd/docgen/docgen.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
local fs = require 'fs'
local emmyPattern = '^%-%-%- (.+)'
local modpattern = '^%-+ @module (%w+)'
local modpattern = '^%-+ @module (.+)'
local pieces = {}

local files = fs.readdir 'nature'
Expand Down Expand Up @@ -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('%?$', '')))
if idx ~= #docs.params then sig = sig .. ', ' end
sig = sig .. param.name:gsub('%?$', '')
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'>
Expand Down
107 changes: 107 additions & 0 deletions docs/api/hilbish/hilbish.messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>

95 changes: 95 additions & 0 deletions docs/api/hilbish/hilbish.runner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'>
Expand Down Expand Up @@ -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>

10 changes: 5 additions & 5 deletions docs/nature/dirs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ menu:
---

<hr>
<div id='setOld'>
<div id='setOld'>
<h4 class='heading'>
dirs.setOld(d)
<a href="#setOld" class='heading-link'>
Expand All @@ -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'>
Expand All @@ -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'>
Expand All @@ -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'>
Expand All @@ -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'>
Expand Down
3 changes: 2 additions & 1 deletion nature/hummingbird.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
-- @module hilbish.messages
local bait = require 'bait'
local commander = require 'commander'
local lunacolors = require 'lunacolors'
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion nature/runner.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
--- hilbish.runner
-- @module hilbish.runner
local currentRunner = 'hybrid'
local runners = {}

Expand Down
Loading