Merge 96369c7 into 72965ad

.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

.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,19 @@
+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

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.
+-- @classmod SILE.classes
+
 local class = pl.class()
 class.type = "class"
 class._name = "base"

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/languages.lua

@@ -1,3 +1,6 @@
+--- SILE language class.
+-- @classmod SILE.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)