doc/lua-filters: autogenerate docs for module pandoc.template

4 files changed, 74 insertions, 31 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 5ca68bdb5..8ae6e3f8e 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -6126,10 +6126,14 @@ Returns:
 
 <!-- END: AUTOGENERATED CONTENT -->
 
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.template -->
+
 # Module pandoc.template
 
 Handle pandoc templates.
 
+## Functions {#pandoc.template-functions}
+
 ### apply {#pandoc.template.apply}
 
 `apply (template, context)`
@@ -6143,7 +6147,7 @@ aforementioned types, or a nested context.
 Parameters:
 
 `template`
-:   template to apply ([Template]{#type-template})
+:   template to apply ([Template])
 
 `context`
 :   variable values (table)
@@ -6152,17 +6156,19 @@ Returns:
 
 -   rendered template ([Doc])
 
+*Since: 3.0*
+
 ### compile {#pandoc.template.compile}
 
 `compile (template[, templates_path])`
 
-Compiles a template string into a [Template](#type-template)
-object usable by pandoc.
+Compiles a template string into a [Template] object usable by
+pandoc.
 
-If the `templates_path` parameter is specified, should be the
-file path associated with the template. It is used when checking
-for partials. Partials will be taken only from the default data
-files if this parameter is omitted.
+If the `templates_path` parameter is specified, then it should be
+the file path associated with the template. It is used when
+checking for partials. Partials will be taken only from the
+default data files if this parameter is omitted.
 
 An error is raised if compilation fails.
 
@@ -6178,32 +6184,36 @@ Parameters:
 
 Returns:
 
--   compiled template (Template)
+-   compiled template ([Template])
+
+*Since: 2.17*
 
 ### default {#pandoc.template.default}
 
 `default ([writer])`
 
 Returns the default template for a given writer as a string. An
-error if no such template can be found.
+error is thrown if no such template can be found.
 
 Parameters:
 
 `writer`
-:   name of the writer for which the template should be
-    retrieved; defaults to the global `FORMAT`.
+:   name of the writer for which the template should be retrieved;
+    defaults to the global `FORMAT`. (string)
 
 Returns:
 
 -   raw template (string)
 
+*Since: 2.17*
+
 ### meta_to_context {#pandoc.template.meta_to_context}
 
 `meta_to_context (meta, blocks_writer, inlines_writer)`
 
-Creates template context from the document's [Meta]{#type-meta}
-data, using the given functions to convert [Blocks] and [Inlines]
-to [Doc] values.
+Creates template context from the document's [Meta] data, using
+the given functions to convert [Blocks] and [Inlines] to [Doc]
+values.
 
 Parameters:
 
@@ -6220,6 +6230,10 @@ Returns:
 
 -   template context (table)
 
+*Since: 3.0*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
 <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.types -->
 
 # Module pandoc.types
@@ -6468,5 +6482,8 @@ Returns:
   [null]: #pandoc.json.null
   [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html
   [ChunkedDoc]: #type-chunkeddoc
+  [Doc]: #type-doc
+  [Template]: #type-template
+  [Meta]: #type-meta
   [zip.Entry]: #type-pandoc.zip.Entry
   [zip.Archive]: #type-pandoc.zip.Archive
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs
index b5497a14d..69dc75955 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs
@@ -31,7 +31,7 @@ documentedModule :: Module PandocError
 documentedModule = Module
   { moduleName = "pandoc.template"
   , moduleDescription = T.unlines
-    [ "Lua functions for pandoc templates."
+    [ "Handle pandoc templates."
     ]
   , moduleFields = []
   , moduleOperations = []
@@ -50,7 +50,7 @@ functions =
      #? T.unlines
      [ "Applies a context with variable assignments to a template,"
      , "returning the rendered template. The `context` parameter must be a"
-     , "table with variable names as keys and [Doc], string, boolean, or"
+     , "table with variable names as keys and [[Doc]], string, boolean, or"
      , "table as values, where the table can be either be a list of the"
      , "aforementioned types, or a nested context."
      ]
@@ -63,9 +63,22 @@ functions =
              Nothing -> runWithDefaultPartials
                         (compileTemplate "templates/default" template))
      <#> parameter peekText "string" "template" "template string"
-     <#> opt (stringParam "templ_path" "template path")
-     =#> functionResult (either failLua pushTemplate) "pandoc Template"
+     <#> opt (stringParam "templates_path"
+              ("parameter to determine a default path and extension for " <>
+               "partials; uses the data files templates path by default."))
+     =#> functionResult (either failLua pushTemplate) "Template"
            "compiled template"
+     #? T.unlines
+     [ "Compiles a template string into a [[Template]] object usable by"
+     , "pandoc."
+     , ""
+     , "If the `templates_path` parameter is specified, then it should be the"
+     , "file path associated with the template. It is used when checking"
+     , "for partials. Partials will be taken only from the default data"
+     , "files if this parameter is omitted."
+     , ""
+     , "An error is raised if compilation fails."
+     ]
     `since` makeVersion [2,17]
 
   , defun "default"
@@ -76,9 +89,14 @@ functions =
            format <- maybe getFORMAT pure mformat
            getDefaultTemplate format)
      <#> opt (textParam "writer"
-              "writer for which the template should be returned.")
+              ("name of the writer for which the template should be " <>
+               "retrieved; defaults to the global `FORMAT`."))
      =#> functionResult pushText "string"
-           "string representation of the writer's default template"
+           "raw template"
+    #? T.unlines
+    [ "Returns the default template for a given writer as a string. An"
+    , "error is thrown if no such template can be found."
+    ]
     `since` makeVersion [2,17]
 
   , defun "meta_to_context"
@@ -96,14 +114,14 @@ functions =
              metaToContext' blockWriter inlineWriter meta)
      <#> parameter peekMeta "Meta" "meta" "document metadata"
      <#> parameter pure "function" "blocks_writer"
-           "converter from Blocks to Doc values"
+           "converter from [[Blocks]] to [[Doc]] values"
      <#> parameter pure "function" "inlines_writer"
-           "converter from Inlines to Doc values"
+           "converter from [[Inlines]] to [[Doc]] values"
      =#> functionResult pushContext "table" "template context"
      #? T.unlines
-     [ "Creates template context from the document's [Meta]{#type-meta}"
-     , "data, using the given functions to convert [Blocks] and [Inlines]"
-     , "to [Doc] values."
+     [ "Creates template context from the document's [[Meta]] data, using the"
+     , "given functions to convert [[Blocks]] and [[Inlines]] to [[Doc]]"
+     , "values."
      ]
     `since` makeVersion [3,0]
   ]
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs
index 8fe24fd6c..fd3006ba6 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs
@@ -263,7 +263,6 @@ run_lua_filter = defun "run_lua_filter"
        "\n\nThe filter will be run in the current Lua process." <>
        "\n"
      )
-  `since` makeVersion [3,2,1]
   where
     copynext :: LuaError e => StackIndex -> LuaE e StackIndex
     copynext to =
diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua
index 12651f966..a13ffdadc 100644
--- a/tools/update-lua-module-docs.lua
+++ b/tools/update-lua-module-docs.lua
@@ -68,12 +68,15 @@ end
 local known_types = {
   Block = 'type-block',
   Blocks = 'type-blocks',
+  Doc = 'type-doc',
   ChunkedDoc = 'type-chunkeddoc',
   Inline = 'type-inline',
   Inlines = 'type-inlines',
+  Meta = 'type-meta',
   Pandoc = 'type-pandoc',
   SimpleTable = 'type-simpletable',
   Table = 'type-table',
+  Template = 'type-template',
   WriterOptions = 'type-writeroptions',
   Version = 'type-version',
 }
@@ -221,6 +224,12 @@ end
 -- @param modulename  name of the module that contains this function
 -- @return {Block,...}
 local function render_type (name, level, modulename)
+  -- FIXME: SPECIAL CASE
+  -- Ignore Template type in `pandoc.template` module, as the automatic
+  -- content doesn't describe it yet.
+  if name == 'pandoc Template' then
+    return {}
+  end
   -- We just want the modulename prefix, as the type names should already
   -- contain the module name to some extend.
   local nameprefix = modulename and
@@ -285,11 +294,11 @@ local function render_module (doc)
 
   local typedocs = Blocks{}
   local types = type(doc.types) == 'function' and doc.types() or {}
-  if #types > 0 then
-    typedocs:insert(Header(2, 'Types', {doc.name .. '-' .. 'types'}))
-    for _, ty in ipairs(types) do
-      typedocs:extend(render_type(ty, 3, doc.name))
-    end
+  for _, ty in ipairs(types) do
+    typedocs:extend(render_type(ty, 3, doc.name))
+  end
+  if #typedocs > 0 then
+    typedocs:insert(1, Header(2, 'Types', {doc.name .. '-' .. 'types'}))
   end
 
   return Blocks{