lua-filters.md: Partially autogenerate docs for module "pandoc"

The documentation system isn't powerful enough to generate the full
documentation automatically.

1 files changed, 69 insertions, 10 deletions

diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua
index 3680c4640..1491cc7dd 100644
--- a/tools/update-lua-module-docs.lua
+++ b/tools/update-lua-module-docs.lua
@@ -21,14 +21,21 @@ local BulletList, DefinitionList, Header, Para, Plain, RawBlock =
 
 local registry = debug.getregistry()
 
---- Table containing all known modules
-local modules = pandoc
-
 --- Retrieves the documentation object for the given value.
 local function documentation (value)
   return registry['HsLua docs'][value]
 end
 
+--- Table containing all known modules
+local modules = {}
+for k, v in pairs(pandoc) do
+  local docs = documentation(v)
+  if docs and docs.fields then
+    modules[k] = v
+  end
+end
+modules['pandoc'] = pandoc
+
 --- Creates an iterator triple that will return values sorted by key names.
 -- @param tbl  table with string keys
 -- @return iterator triple to be used in a `for` loop.
@@ -66,16 +73,32 @@ end
 
 --- Map of all known data types to a heading ID. Used to create hyperlinks.
 local known_types = {
+  Alignment = 'type-alignment',
+  Attr = 'type-attr',
+  AttributeList = 'type-attributes',
   Block = 'type-block',
   Blocks = 'type-blocks',
+  Caption = 'type-caption',
+  Cell = 'type-cell',
+  ColSpec = 'type-colspec',
   Doc = 'type-doc',
   ChunkedDoc = 'type-chunkeddoc',
+  Figure = 'type-figure',
   Inline = 'type-inline',
   Inlines = 'type-inlines',
+  ListAttributes = 'type-listattributes',
   Meta = 'type-meta',
+  MetaValue = 'type-metavalue',
   Pandoc = 'type-pandoc',
+  ReaderOptions = 'type-readeroptions',
+  Row = 'type-row',
   SimpleTable = 'type-simpletable',
+  Span = 'type-span',
+  Str = 'type-str',
   Table = 'type-table',
+  TableBody = 'type-tablebody',
+  TableHead = 'type-tablehead',
+  TableFoot = 'type-tablefoot',
   Template = 'type-template',
   WriterOptions = 'type-writeroptions',
   Version = 'type-version',
@@ -264,16 +287,16 @@ local function render_type (name, level, modulename)
     end
   end
 
+  local type_description = properties .. methods
   if name == 'Doc' then
-    local header_id = 'type-' .. nameprefix .. '.' .. name
-    return {Header(level, name, {header_id})} ..
-      Blocks{Para {"See the description ", Link("above", "#type-doc"), "."}}
+    type_description = Blocks{
+      Para {"See the description ", Link("above", "#type-doc"), "."}
+    }
   end
   local header_id = 'type-' .. nameprefix .. '.' .. name
-  known_types[name] = header_id
+  known_types[name] = known_types[name] or header_id
   return {Header(level, name, {header_id})} ..
-    properties ..
-    methods
+    type_description
 end
 
 --- Renders module documentation.
@@ -314,6 +337,39 @@ local function render_module (doc)
     typedocs
 end
 
+--- Renders the documentation of the main "pandoc" module.
+-- FIXME: This function shouldn't exist.
+local function render_main_pandoc_module (doc)
+  local constants_section = Blocks{Header(2, "Constants")}
+  local fields = List{}
+  for i, field in ipairs(doc.fields) do
+    if tostring(field.type) == 'string' then
+      constants_section:extend(render_field(field, 2, "pandoc"))
+    elseif field.name:match '^[A-Z]' then
+      -- Ignore (these are the `Block` and `Inline` tables)
+    else
+      fields:insert(field)
+    end
+  end
+  local stop_rendering = false
+  local functions = List{}
+  for _, fn in ipairs(doc.functions) do
+    if stop_rendering then
+      pandoc.log.info("Not rendered in module pandoc: " .. fn.name .. '\n')
+    else
+      functions:insert(fn)
+    end
+    if fn.name == 'SimpleTable' then
+      stop_rendering = true
+    end
+  end
+  doc.fields = fields
+  doc.functions = functions
+  -- product types don't render well, so we document those manually
+  doc.types = {}
+  return render_module(doc)
+end
+
 local autogen_start =
   '\n<!%-%- BEGIN: AUTOGENERATED CONTENT for module ([a-z%.]+) %-%->'
 local autogen_end =
@@ -336,7 +392,10 @@ local function process_document (input, blocks, start)
     print('Generating docs for module ' .. module_name)
     blocks:insert(rawmd(input:sub(start, mstop)))
     local object = modules[module_name] or modules[module_name:gsub('^pandoc%.', '')]
-    blocks:extend(render_module(documentation(object)))
+    local docblocks = (object == pandoc)
+      and render_main_pandoc_module(documentation(object))
+      or render_module(documentation(object))
+    blocks:extend(docblocks)
     return process_document(input, blocks, input:find(autogen_end, mstop) or -1)
   else
     local reflinks_stop = select(2, input:find(reflinks_marker, start))