Merge pull request #1998 from alerque/ldoc

.cirrus.yml

@@ -42,7 +42,7 @@ task:
     - ./bootstrap.sh
   configure_script: |
     ./configure MAKE=gmake \
-      --enable-developer LUAROCKS=false LUACHECK=false BUSTED=false DELTA=cat PDFINFO=false NIX=false NPM=false DOCKER=false \
+      --enable-developer LDOC=false LUAROCKS=false LUACHECK=false BUSTED=false DELTA=cat PDFINFO=false NIX=false NPM=false DOCKER=false \
       --disable-font-variations \
       --with-system-lua-sources \
       --with-system-luarocks \

.commitlintrc.yml

@@ -39,6 +39,7 @@ rules:
     - inputters
     - installation
     - languages
+    - api
     - manpage
     - manual
     - math

.editorconfig

@@ -17,7 +17,7 @@ indent_size = 8
 [*.md]
 trim_trailing_whitespace = false
 
-[{*.lua,*.lua.in,sile.in,*rockspec,.busted,.luacheckrc}]
+[{*.lua,*.lua.in,sile.in,*rockspec,.busted,.luacheckrc,config.ld}]
 indent_style = space
 indent_size = 3
 max_line_length = 120

.github/workflows/coverage.yml

@@ -60,7 +60,7 @@ jobs:
         run: |
           ./bootstrap.sh
           ./configure \
-            --enable-developer LUACHECK=false NIX=false DELTA=cat \
+            --enable-developer LDOC=false LUACHECK=false NIX=false DELTA=cat \
             --disable-font-variations \
             --without-manual
       - name: Make

.github/workflows/test.yml

@@ -71,7 +71,7 @@ jobs:
           ./bootstrap.sh
           ./configure \
             ${{ matrix.luaVersion[1] }} \
-            --enable-developer LUACHECK=false NIX=false DELTA=cat \
+            --enable-developer LDOC=false LUACHECK=false NIX=false DELTA=cat \
             --disable-font-variations \
             --with${{ !startsWith(matrix.luaVersion[0], 'luajit') && 'out' || '' }}-luajit \
             --without-system-luarocks \

Makefile.am

@@ -70,7 +70,7 @@ dist_pdf_DATA = $(_MANUAL)
 dist_license_DATA = LICENSE.md
 EXTRA_DIST = spec tests documentation sile-dev-1.rockspec fontconfig.conf
 EXTRA_DIST += Makefile-distfiles
-EXTRA_DIST += build-aux/action-updater.js build-aux/cargo-updater.js build-aux/decore-automake.sh build-aux/git-version-gen build-aux/list-dist-files.sh
+EXTRA_DIST += build-aux/action-updater.js build-aux/cargo-updater.js build-aux/config.ld build-aux/decore-automake.sh build-aux/git-version-gen build-aux/list-dist-files.sh
 EXTRA_DIST += Dockerfile build-aux/docker-bootstrap.sh build-aux/docker-fontconfig.conf hooks/build
 EXTRA_DIST += default.nix flake.nix flake.lock shell.nix build-aux/pkg.nix
 EXTRA_DIST += package.json # imported by both Nix and Docker
@@ -173,7 +173,13 @@ selfcheck: | $(bin_PROGRAMS) $(_BUILT_SUBDIRS)
 	$(PDFINFO) $$output | $(GREP) "SILE v$(VERSION)"
 
 .PHONY: docs
-docs: $(_MANUAL)
+docs: $(_MANUAL) lua-api-docs
+
+.PHONY: lua-api-docs
+lua-api-docs: lua-api-docs/index.html
+
+lua-api-docs/index.html: build-aux/config.ld
+	$(LDOC) -c build-aux/config.ld .
 
 .PHONY: docs-figures
 docs-figures: $(FIGURES)

build-aux/config.ld

@@ -0,0 +1,23 @@
+project = "SILE"
+description = "The SILE Typesetter"
+readme = "../README.md"
+dir = "../lua-api-docs"
+format = "discount"
+file = {
+  "../sile-lua",
+  "../core/",
+  "../classes/",
+  "../inputters/",
+  "../languages/",
+  "../outputters/",
+  "../packages/",
+  "../pagebuilders/",
+  "../shapers/",
+  "../types/",
+  "../typesetters/",
+}
+merge = true
+no_space_before_args = true
+sort_modules = true
+new_type("interfaces", "Interfaces", true)
+new_type("types", "Types", true)

build-aux/pkg.nix

@@ -47,6 +47,8 @@ let
     # lua packages needed for testing
     busted
     luacheck
+    # packages needed for building api docs
+    ldoc
   # NOTE: Add lua packages here, to change the luaEnv also read by `flake.nix`
   ] ++ lib.optionals (lib.versionOlder lua.luaversion "5.2") [
     bit32

classes/base.lua

@@ -1,3 +1,6 @@
+--- SILE document class class.
+-- @interfaces classes
+
 local class = pl.class()
 class.type = "class"
 class._name = "base"
@@ -277,6 +280,18 @@ function class:runHooks (category, options)
   end
 end
 
+--- Register a function as a SILE command.
+-- Takes any Lua function and registers it for use as a SILE command (which will in turn be used to process any content
+-- nodes identified with the command name.
+--
+-- Note that this should only be used to register commands supplied directly by a document class. A similar method is
+-- available for packages, `packages:registerCommand`.
+-- @tparam string name Name of cammand to register.
+-- @tparam function func Callback function to use as command handler.
+-- @tparam[opt] nil|string help User friendly short usage string for use in error messages, documentation, etc.
+-- @tparam[opt] nil|string pack Information identifying the module registering the command for use in error and usage
+-- messages. Usually auto-detected.
+-- @see SILE.packages:registerCommand
 function class.registerCommand (_, name, func, help, pack)
   SILE.Commands[name] = func
   if not pack then

configure.ac

@@ -220,6 +220,7 @@ AM_COND_IF([DEPENDENCY_CHECKS], [
         AX_PROGVAR([git])
         AX_PROGVAR([grep])
         AX_PROGVAR([head])
+        AX_PROGVAR([ldoc])
         AX_PROGVAR([luacheck])
         AX_PROGVAR([luarocks])
         AX_PROGVAR([nix])

core/deprecations.lua

@@ -138,6 +138,14 @@ setmetatable(SILE.PackageManager, {
   __index = nopackagemanager
 })
 
+SU.utf8char = function ()
+  SU.deprecated("SU.utf8char", "luautf8.char", "0.11.0", "0.12.0")
+end
+
+SU.utf8codes = function ()
+  SU.deprecated("SU.utf8codes", "luautf8.codes", "0.11.0", "0.12.0")
+end
+
 -- luacheck: ignore updatePackage
 -- luacheck: ignore installPackage
 updatePackage = nopackagemanager

core/font.lua

@@ -1,3 +1,5 @@
+--- font
+-- @module SILE.font
 local icu = require("justenoughicu")
 
 local lastshaper

core/globals.lua

@@ -0,0 +1,26 @@
+--- Global library provisions.
+-- @module globals
+-- @alias _G
+
+--- Penlight od-demand loader.
+-- The Lua language adopts a "no batteries included" philosophy by providing a minimal standard library. Penlight is
+-- a widely used set libraries for making it easier to work with common tasks. Loading SILE implies that the PEnlight
+-- on-demand module loader is available, allowing any Penlight functions to be accessed using the `pl` prefix. Consult
+-- the [Penlight documentation](https://lunarmodules.github.io/Penlight/) for specifics of the utilities available.
+_G.pl = require("pl.import_into")()
+
+--- UTF-8 string library.
+-- LuaJIT 5.1 and 5.2's `string` module only handle strings as bytes. Lua 5.3+ has a UTF-8 safe `string` module, but its
+-- feature set is somewhat underwhelming. This module includes more functions and levels the playing field no matter
+-- which Lua VM is being used. See [luautf8 docs](https://github.com/starwing/luautf8) for more details.
+_G.luautf8 = require("lua-utf8")
+
+--- Fluent localization library.
+-- For handling messages in various languages SILE provides an implementation of [Project
+-- Fluent](https://projectfluent.org/)'s localization system (originally developed by Mozilla for use in Firefox). This
+-- global is an instantiated interface to [fluent-lua](https://github.com/alerque/fluent-lua) pre-loaded with resources
+-- for all the langugaes and regions SILE has support for.
+_G.fluent = require("fluent")()
+
+-- For developer testing only, usually in CI
+if os.getenv("SILE_COVERAGE") then require("luacov") end

core/languages.lua

@@ -1,3 +1,6 @@
+--- SILE language class.
+-- @interfaces languages
+
 local loadkit = require("loadkit")
 local cldr = require("cldr")
 

core/settings.lua

@@ -1,7 +1,11 @@
+--- core settings instance
+--- @module SILE.settings
+
 local deprecator = function ()
   SU.deprecated("SILE.settings.*", "SILE.settings:*", "0.13.0", "0.15.0")
 end
 
+--- @type settings
 local settings = pl.class()
 
 function settings:_init()
@@ -98,12 +102,14 @@ function settings:_init()
 
 end
 
+--- Stash the current values of all settings in a stack to be returned to later
 function settings:pushState ()
   if not self then return deprecator() end
   table.insert(self.stateQueue, self.state)
   self.state = pl.tablex.copy(self.state)
 end
 
+--- Return the most recently pushed set of values in the setting stack
 function settings:popState ()
   if not self then return deprecator() end
   local previous = self.state
@@ -118,6 +124,8 @@ function settings:popState ()
   end
 end
 
+--- Declare a new setting
+--- @tparam table specs { parameter, type, default, help, hook, ... } declaration specification
 function settings:declare (spec)
   if not spec then return deprecator() end
   if spec.name then
@@ -135,7 +143,7 @@ function settings:declare (spec)
   self:set(spec.parameter, spec.default, true)
 end
 
---- Reset all settings to their default value.
+--- Reset all settings to their registered default values.
 function settings:reset ()
   if not self then return deprecator() end
   for k,_ in pairs(self.state) do
@@ -144,8 +152,7 @@ function settings:reset ()
 end
 
 --- Restore all settings to the value they had in the top-level state,
--- that is at the head of the settings stack (normally the document
--- level).
+-- that is at the tap of the settings stack (normally the document level).
 function settings:toplevelState ()
   if not self then return deprecator() end
   if #self.stateQueue ~= 0 then
@@ -158,6 +165,9 @@ function settings:toplevelState ()
   end
 end
 
+--- Get the value of a setting
+-- @tparam string parameter The full name of the setting to fetch.
+-- @return Value of setting
 function settings:get (parameter)
   -- HACK FIXME https://github.com/sile-typesetter/sile/issues/1699
   -- See comment on set() below.
@@ -175,6 +185,11 @@ function settings:get (parameter)
   end
 end
 
+--- Set the value of a setting
+-- @tparam string parameter The full name of the setting to change.
+-- @param value The new value to change it to.
+-- @tparam[opt=false] boolean makedefault Whether to make this the new default value.
+-- @tparam[opt=false] boolean reset Whether to reset the value to the current default value.
 function settings:set (parameter, value, makedefault, reset)
   -- HACK FIXME https://github.com/sile-typesetter/sile/issues/1699
   -- Anything dubbed current.xxx should likely NOT be a "setting" (subject
@@ -219,10 +234,16 @@ function settings:set (parameter, value, makedefault, reset)
   self:runHooks(parameter, value)
 end
 
+--- Register a callback hook to be run when a setting changes.
+-- @tparam string parameter Name of the setting to add a hook to.
+-- @tparam function func Callback function accepting one argument (the new value).
 function settings:registerHook (parameter, func)
    table.insert(self.hooks[parameter], func)
 end
 
+--- Trigger execution of callback hooks for a given setting.
+-- @tparam string parameter The name of the parameter changes.
+-- @param value The new value of the setting, passed as the first argument to the hook function.
 function settings:runHooks (parameter, value)
   if self.hooks[parameter] then
     for _, func in ipairs(self.hooks[parameter]) do
@@ -232,14 +253,20 @@ function settings:runHooks (parameter, value)
   end
 end
 
+--- Isolate a block of processing so that setting changes made during the block don't last past the block.
+-- (Under the hood this just uses `:pushState()`, the processes the function, then runs `:popState()`)
+-- @tparam function func A function wrapping the actions to take without affecting settings for future use.
 function settings:temporarily (func)
   if not func then return deprecator() end
   self:pushState()
   func()
   self:popState()
 end
 
-function settings:wrap () -- Returns a closure which applies the current state, later
+--- Create a settings wrapper function that applies current settings to later content processing.
+--- @treturn function a closure fuction accepting one argument (content) to process using
+--- typesetter settings as they are at the time of closure creation.
+function settings:wrap ()
   if not self then return deprecator() end
   local clSettings = pl.tablex.copy(self.state)
   return function(content)