Lua: add function `pandoc.utils.documentation` (#11383)

Closes #10999.

This is now used to generate much of the Lua API documentation.

1 files changed, 63 insertions, 36 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 2c82447f9..39e5988fc 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -4163,7 +4163,7 @@ Parameters:
 
 Returns:
 
--  ([Inlines])
+- ([Inlines])
 
 *Since: 2.2.3*
 
@@ -4193,6 +4193,24 @@ Returns:
 
 *Since: 2.19.1*
 
+### documentation {#pandoc.utils.documentation}
+
+`documentation (object[, format])`
+
+Parameters:
+
+`object`
+:   Retrieve documentation for this object (any)
+
+`format`
+:   result format (string\|table)
+
+Returns:
+
+- rendered documentation (string\|[Blocks])
+
+*Since: 3.8.4*
+
 ### equals {#pandoc.utils.equals}
 
 `equals (element1, element2)`
@@ -4207,10 +4225,10 @@ operator instead.
 Parameters:
 
 `element1`
-:    (any)
+:   (any)
 
 `element2`
-:    (any)
+:   (any)
 
 Returns:
 
@@ -4237,7 +4255,7 @@ Usage:
 Parameters:
 
 `simple_tbl`
-:    ([SimpleTable])
+:   ([SimpleTable])
 
 Returns:
 
@@ -4264,8 +4282,7 @@ Parameters:
     attribute containing the section number. (boolean)
 
 `baselevel`
-:   shift top-level headings to this level
-    ([integer]{unknown-type="integer"}\|nil)
+:   shift top-level headings to this level (integer\|nil)
 
 `blocks`
 :   list of blocks to process ([Blocks])
@@ -4292,8 +4309,7 @@ Parameters:
 
 Returns:
 
-- normalized date, or nil if normalization failed. ([string or
-  nil]{unknown-type="string or nil"})
+- normalized date, or nil if normalization failed. (string\|nil)
 
 *Since: 2.0.6*
 
@@ -4389,7 +4405,7 @@ Computes the SHA1 hash of the given string input.
 Parameters:
 
 `input`
-:    (string)
+:   (string)
 
 Returns:
 
@@ -4407,8 +4423,8 @@ string with all formatting removed.
 Parameters:
 
 `element`
-:   some pandoc AST element ([AST
-    element]{unknown-type="AST element"})
+:   some pandoc AST element
+    ([Pandoc]\|[Block]\|[Inline]\|[Caption]\|[Cell]\|[MetaValue])
 
 Returns:
 
@@ -4431,8 +4447,7 @@ Usage:
 Parameters:
 
 `n`
-:   positive integer below 4000
-    ([integer]{unknown-type="integer"})
+:   positive integer below 4000 (integer)
 
 Returns:
 
@@ -4509,8 +4524,8 @@ Creates a Version object.
 Parameters:
 
 `v`
-:   version description ([version string, list of integers, or
-    integer]{unknown-type="version string, list of integers, or integer"})
+:   version description
+    ([Version]\|string\|{integer,\...}\|number)
 
 Returns:
 
@@ -4583,6 +4598,7 @@ Returns:
 
 - The entry's MIME type, or `nil` if the file was not found.
   (string)
+
 - Contents of the file, or `nil` if the file was not found.
   (string)
 
@@ -4630,7 +4646,8 @@ Parameters:
 :   filename and path relative to the output folder. (string)
 
 `mimetype`
-:   the item's MIME type; omit if unknown or unavailable. (string)
+:   the item's MIME type; use `nil` if the MIME type is unknown or
+    unavailable. (string\|nil)
 
 `contents`
 :   the binary contents of the file. (string)
@@ -4714,6 +4731,7 @@ Returns:
 
 - The entry's MIME type, or nil if the file was not found.
   (string)
+
 - Contents of the file, or nil if the file was not found. (string)
 
 *Since: 2.0*
@@ -5044,8 +5062,7 @@ Parameters:
 
 Returns:
 
-- all extensions supported for `format`
-  ([FormatExtensions]{unknown-type="FormatExtensions"})
+- all extensions supported for `format` ([FormatExtensions])
 
 *Since: 3.0*
 
@@ -5064,8 +5081,7 @@ Parameters:
 
 Returns:
 
-- default extensions enabled for `format`
-  ([FormatExtensions]{unknown-type="FormatExtensions"})
+- default extensions enabled for `format` ([FormatExtensions])
 
 *Since: 3.0*
 
@@ -5516,6 +5532,7 @@ Parameters:
 Returns:
 
 - filepath without extension (string)
+
 - extension or empty string (string)
 
 *Since: 2.12*
@@ -5616,7 +5633,7 @@ Parameters:
 
 Returns:
 
-- slide level ([integer]{unknown-type="integer"})
+- slide level (integer)
 
 *Since: 3.0*
 
@@ -5665,7 +5682,7 @@ Parameters:
 
 Returns:
 
--  ([ChunkedDoc])
+- ([ChunkedDoc])
 
 *Since: 3.0*
 
@@ -5765,7 +5782,7 @@ versions and on different platforms.
 
 Returns:
 
-- CPU time in picoseconds ([integer]{unknown-type="integer"})
+- CPU time in picoseconds (integer)
 
 *Since: 3.1.1*
 
@@ -5793,8 +5810,10 @@ Parameters:
 Returns:
 
 - exit code -- `false` on success, an integer otherwise
-  ([integer]{unknown-type="integer"}\|boolean)
+  (integer\|boolean)
+
 - stdout (string)
+
 - stderr (string)
 
 *Since: 3.7.1*
@@ -5971,6 +5990,7 @@ Parameters:
 Returns:
 
 - time at which the file or directory was last modified (table)
+
 - time at which the file or directory was last accessed (table)
 
 *Since: 3.7.1*
@@ -6106,7 +6126,10 @@ Returns:
 <!-- END: AUTOGENERATED CONTENT -->
 
 
-<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.layout -->
+<!-- Auto-generation temporarily disabled; needs updates in the documenation
+renderer and in `hslua-packaging`. -->
+
+<!-- BEGIN DISABLED: AUTOGENERATED CONTENT for module pandoc.layout -->
 
 # Module pandoc.layout
 
@@ -6822,6 +6845,7 @@ Scaffolding for custom writers.
 An object to be used as a `Writer` function; the construct handles
 most of the boilerplate, expecting only render functions for all
 AST elements (table)
+
 <!-- END: AUTOGENERATED CONTENT -->
 
 <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.text -->
@@ -6885,7 +6909,7 @@ Parameters:
 
 Returns:
 
-- length ([integer]{unknown-type="integer"}\|string)
+- length (integer\|string)
 
 *Since: 2.0.3*
 
@@ -6936,10 +6960,10 @@ Parameters:
 :   UTF-8 string (string)
 
 `i`
-:   substring start position ([integer]{unknown-type="integer"})
+:   substring start position (integer)
 
 `j`
-:   substring end position ([integer]{unknown-type="integer"})
+:   substring end position (integer)
 
 Returns:
 
@@ -7165,7 +7189,7 @@ Returns:
 
 ## Types {#pandoc.template-types}
 
-### Template {#type-pandoc.Template}
+### Template {#type-pandoc.template.Template}
 
 <!-- END: AUTOGENERATED CONTENT -->
 
@@ -7186,7 +7210,7 @@ Parameters:
 `version_specifier`
 :   A version string like `'2.7.3'`, a Lua number like `2.0`, a
     list of integers like `{2,7,3}`, or a Version object.
-    (string\|number\|{[integer]{unknown-type="integer"},\...}\|[Version])
+    (string\|number\|{integer,\...}\|[Version])
 
 Returns:
 
@@ -7196,7 +7220,9 @@ Returns:
 
 <!-- END: AUTOGENERATED CONTENT -->
 
-<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.zip -->
+<!-- Disabled due to limitations in the current documentation
+     renderer. -->
+<!-- BEGIN DISABLED: AUTOGENERATED CONTENT for module pandoc.zip -->
 
 # Module pandoc.zip
 
@@ -7255,7 +7281,7 @@ Parameters:
 :   uncompressed contents (string)
 
 `modtime`
-:   modification time ([integer]{unknown-type="integer"})
+:   modification time (integer)
 
 Returns:
 
@@ -7272,7 +7298,7 @@ Generates a ZipEntry from a file or directory.
 Parameters:
 
 `filepath`
-:    (string)
+:   (string)
 
 `opts`
 :   zip options (table)
@@ -7399,7 +7425,9 @@ Returns:
 
 - link target if entry represents a symbolic link (string\|nil)
 
-<!-- END: AUTOGENERATED CONTENT -->
+[zip.Entry]: #type-pandoc.zip.Entry
+[zip.Archive]: #type-pandoc.zip.Archive
+<!-- END DISABLED: AUTOGENERATED CONTENT -->
 
 <!-- BEGIN: GENERATED REFERENCE LINKS -->
 
@@ -7428,6 +7456,7 @@ Returns:
   [Table]: #type-table
   [Version]: #type-version
   [`list`]: #pandoc.mediabag.list
+  [FormatExtensions]: #FormatExtensions
   [WriterOptions]: #type-writeroptions
   [null]: #pandoc.json.null
   [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html
@@ -7435,5 +7464,3 @@ Returns:
   [XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/latest/
   [Doc]: #type-doc
   [Template]: #type-template
-  [zip.Entry]: #type-pandoc.zip.Entry
-  [zip.Archive]: #type-pandoc.zip.Archive