Add API docs from LDoc comments

.github/workflows/mdbook.yaml

@@ -29,6 +29,14 @@ jobs:
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v4
+      - name: Generate API docs
+        run:
+          alias ldoc='docker run -v "$(pwd):/data" ghcr.io/lunarmodules/ldoc:latest'
+          cd docs/api/
+          ldoc -c gremlin.ldoc
+          ldoc -c evac.ldoc
+          ldoc -c ungency.ldoc
+          ldoc -c waves.ldoc
       - name: Build with mdBook
         run: mdbook build
       - name: Upload artifact

.gitignore

@@ -2,3 +2,4 @@ DCS_header_extracted.lua
 CTLD_*.lua
 CSAR_*.lua
 book
+docs/api/*.md

docs/SUMMARY.md

@@ -43,3 +43,10 @@
 # Book-Keeping
 
 - [Contributors](./contributors.md)
+
+# API
+
+- [Gremlin](./api/gremlin.md)
+- [Evac](./api/evac.md)
+- [Urgency](./api/urgency.md)
+- [Waves](./api/waves.md)

docs/api/evac.ldoc

@@ -0,0 +1,16 @@
+file = '../../src/evac.lua'
+project = 'Gremlin Evac'
+title = 'Gremlin Evac'
+package = '../../src'
+description = 'Documenting Gremlin Evac'
+template = true
+template_escape = '>'
+dir = '.'
+output = 'evac'
+ext = 'md'
+merge = true
+sort = true
+custom_tags = {
+    { 'diagnostic', hidden = true }
+}
+no_space_before_args = true

docs/api/gremlin.ldoc

@@ -0,0 +1,16 @@
+file = '../../src/gremlin.lua'
+project = 'Gremlin Script Tools'
+title = 'Gremlin Script Tools'
+package = '../../src'
+description = 'Documenting Gremlin Script Tools'
+template = true
+template_escape = '>'
+dir = '.'
+output = 'gremlin'
+ext = 'md'
+merge = true
+sort = true
+custom_tags = {
+    { 'diagnostic', hidden = true }
+}
+no_space_before_args = true

docs/api/ldoc.ltp

@@ -0,0 +1,239 @@
+> local lev = ldoc.level or 1
+> local lev1,lev2,lev3 = ('#'):rep(lev),('#'):rep(lev+1),('#'):rep(lev+2)
+> local no_spaces = ldoc.no_spaces
+> local use_li = ldoc.use_li
+> local display_name = ldoc.display_name
+> local iter = ldoc.modules.iter
+> local M = function(txt, item) return ldoc.markup(txt, item, ldoc.plain):gsub('<p>', '\n'):gsub('\n\n+', '\n\n') end
+> local nowrap = ldoc.wrap and '' or 'nowrap'
+>
+> if ldoc.no_summary and module and not ldoc.one then
+>   for kind, items in module.kinds() do
+$(lev2) $(kind)
+
+>     for item in items() do
+- [$(display_name(item))](#$(item.name))
+>     end
+
+>   end
+> end
+> -------- contents of project ----------
+> local this_mod = module and module.name
+> for kind, mods, type in ldoc.kinds() do
+>   if ldoc.allowed_in_contents(type,module) then
+$(lev2) $(kind)
+
+>     for mod in mods() do
+>       local name = display_name(mod)
+>       if mod.name == this_mod then
+- **$(name)**
+>       else
+- [$(name)]($(ldoc.ref_to_module(mod)))
+>       end
+>     end
+>   end
+
+> end
+> if ldoc.body then -- verbatim text as contents; 'non-code' entries
+$(ldoc.body)
+> elseif module then -- module documentation
+$(lev1) $(ldoc.module_typename(module)) `$(module.name)`
+
+$(M(module.summary,module))
+
+$(M(module.description,module))
+
+>   if module.tags.include then
+$(M(ldoc.include_file(module.tags.include)))
+
+>   end
+>   if module.see then
+$(lev3) See also:
+
+>     for see in iter(module.see) do
+- [$(see.label)]($(ldoc.href(see)))
+>     end -- for
+
+>   end -- if see
+>   if module.usage then
+$(lev3) Usage:
+
+>     for usage in iter(module.usage) do
+- `$(ldoc.escape(usage))`
+>     end -- for
+
+>   end -- if usage
+>   if module.info then
+$(lev3) Info:
+
+>     for tag, value in module.info:iter() do
+- **$(tag)**: $(M(value,module))
+>     end
+
+>   end -- if module.info
+>   if not ldoc.no_summary then
+>     -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
+>     for kind,items in module.kinds() do
+$(lev2) [$(kind)](#$(no_spaces(kind)))
+
+| Name | Summary |
+|---|---|
+>       for item in items() do
+| [$(display_name(item))](#$(item.name)) | $(M(item.summary,item)) |
+>       end -- for items
+
+>     end -- for kinds
+>   end -- if not no_summary
+>   local show_return = not ldoc.no_return_or_parms
+>   local show_parms = show_return
+>   for kind, items in module.kinds() do
+>     local kitem = module.kinds:get_item(kind)
+>     local has_description = kitem and ldoc.descript(kitem) ~= ""
+$(lev2) $(kind)
+
+$(M(module.kinds:get_section_description(kind),nil))
+
+>     if kitem then
+>       if has_description then
+$(M(ldoc.descript(kitem),kitem))
+
+>       end
+>       if kitem.usage then
+$(lev3) Usage:
+
+```
+$(ldoc.prettify(kitem.usage[1]))
+```
+
+>       end
+>     end
+>     for item in items() do
+**$(display_name(item))**
+
+>       if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
+[line $(item.lineno)]($(ldoc.source_ref(item)))
+
+>       end
+$(M(ldoc.descript(item),item))
+
+>       if ldoc.custom_tags then
+>         for custom in iter(ldoc.custom_tags) do
+>           local tag = item.tags[custom[1]]
+>           if tag and not custom.hidden then
+$(lev3) $(custom.title or custom[1]):
+
+>             for value in iter(tag) do
+- $(custom.format and custom.format(value) or M(value))
+>             end -- for
+>           end -- if tag
+
+>         end -- iter tags
+>       end
+>       if show_parms and item.params and #item.params > 0 then
+>         local subnames = module.kinds:type_of(item).subnames
+>         if subnames then
+$(lev3) $(subnames):
+>         end
+
+>         for parm in iter(item.params) do
+>           local param,sublist = item:subparam(parm)
+>           if sublist then
+  - $(sublist) $(M(item.params.map[sublist],item))
+>           end
+>           for p in iter(param) do
+>             local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p)
+- $(name)
+>             if tp ~= '' then
+  $(tp)
+>             end
+  $(M(item.params.map[p],item))
+>             if def == true then
+  (_optional_)
+>             elseif def then
+  (_default_ $(def))
+>             end
+>             if item:readonly(p) then
+  _readonly_
+>             end
+>           end
+>         end -- for
+
+>       end -- if params
+>       if show_return and item.retgroups then local groups = item.retgroups
+$(lev3) Returns:
+
+>         for i, group in ldoc.ipairs(groups) do
+>           for r in group:iter() do
+>             local type, ctypes = item:return_type(r)
+>             local rt = ldoc.typename(type)
+-
+>             if rt ~= '' then
+  $(rt)
+>             end
+  $(M(r.text,item))
+
+>             if ctypes then
+>               for c in ctypes:iter() do
+  - $(c.name)
+    $(ldoc.typename(c.type))
+    $(M(c.comment,item))
+>               end
+
+>             end -- if ctypes
+>           end -- for r
+>           if i < #groups then
+
+$(lev3) Or
+
+>           end
+>         end -- for group
+>       end -- if returns
+>       if show_return and item.raise then
+$(lev3) Raises:
+
+$(M(item.raise,item))
+
+>       end
+>       if item.see then
+$(lev3) See also:
+
+>         for see in iter(item.see) do
+- [$(see.label)]($(ldoc.href(see)))
+>         end -- for
+
+>       end -- if see
+>       if item.usage then
+$(lev3) Usage:
+
+>         for usage in iter(item.usage) do
+- `$(ldoc.prettify(usage))`
+>         end -- for
+
+>       end -- if usage
+>     end -- for items
+>   end -- for kinds
+> else -- if module; project-level contents
+>   if ldoc.description then
+$(lev2) $(M(ldoc.description,nil))
+
+>   end
+>   if ldoc.full_description then
+$(M(ldoc.full_description,nil))
+
+>   end
+>   for kind, mods in ldoc.kinds() do
+$(lev2) $(kind)
+
+>     kind = kind:lower()
+
+| Module | Summary |
+|---|---|
+>     for m in mods() do
+| [$(m.name)]($(no_spaces(kind))/$(m.name).md) | $(M(ldoc.strip_header(m.summary),m)) |
+>     end -- for modules
+>   end -- for kinds
+> end -- if module
+> if ldoc.updatetime and ldoc.updatetime ~= "" then
+
+_Last updated $(ldoc.updatetime)_
+> end -- if updatetime

docs/api/urgency.ldoc

@@ -0,0 +1,16 @@
+file = '../../src/urgency.lua'
+project = 'Gremlin Urgency'
+title = 'Gremlin Urgency'
+package = '../../src'
+description = 'Documenting Gremlin Urgency'
+template = true
+template_escape = '>'
+dir = '.'
+output = 'urgency'
+ext = 'md'
+merge = true
+sort = true
+custom_tags = {
+    { 'diagnostic', hidden = true }
+}
+no_space_before_args = true

docs/api/waves.ldoc

@@ -0,0 +1,16 @@
+file = '../../src/waves.lua'
+project = 'Gremlin Waves'
+title = 'Gremlin Waves'
+package = '../../src'
+description = 'Documenting Gremlin Waves'
+template = true
+template_escape = '>'
+dir = '.'
+output = 'waves'
+ext = 'md'
+merge = true
+sort = true
+custom_tags = {
+    { 'diagnostic', hidden = true }
+}
+no_space_before_args = true