Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions1

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

Browse source 
The documentation system isn't powerful enough to generate the full
documentation automatically.
This commit is contained in:
Albert Krewinkel 2024-06-11 15:53:36 +02:00
parent 73ce302479
commit 790abcf414
No known key found for this signature in database
GPG key ID: 388DC0B21F631124
3 changed files with 648 additions and 326 deletions
doc
lua-filters.md
pandoc-lua-engine/src/Text/Pandoc/Lua/Module
Pandoc.hs
tools
update-lua-module-docs.lua

780
doc/lua-filters.md
View file

File diff suppressed because it is too large Load diff

115
pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Pandoc.hs
View file

@ -6,12 +6,10 @@
{- |
Module : Text.Pandoc.Lua.Module.Pandoc
Copyright : Copyright © 2017-2024 Albert Krewinkel
License : GNU GPL, version 2 or above
License : GPL-2.0-or-later
Maintainer : Albert Krewinkel <albert+pandoc@tarleb.com>
Stability : alpha
Pandoc module for lua.
Main @pandoc@ module, containing element constructors and central functions.
-}
module Text.Pandoc.Lua.Module.Pandoc
( documentedModule
@ -61,19 +59,22 @@ documentedModule :: Module PandocError
documentedModule = Module
{ moduleName = "pandoc"
, moduleDescription = T.unlines
[ "Lua functions for pandoc scripts; includes constructors for"
, "document elements, functions to parse text in a given"
[ "Fields and functions for pandoc scripts; includes constructors for"
, "document tree elements, functions to parse text in a given"
, "format, and functions to filter and modify a subtree."
]
, moduleFields = readersField : writersField :
stringConstants ++ [inlineField, blockField]
, moduleOperations = []
, moduleFunctions = mconcat
[ functions
, otherConstructors
, blockConstructors
, inlineConstructors
[ [mkPandoc, mkMeta]
, metaValueConstructors
, blockConstructors
, [mkBlocks]
, inlineConstructors
, [mkInlines]
, otherConstructors
, functions
]
, moduleTypeInitializers =
[ initType typePandoc
@ -144,30 +145,51 @@ pushWithConstructorsSubtable constructors = do
otherConstructors :: [DocumentedFunction PandocError]
otherConstructors =
[ mkPandoc
, mkMeta
, mkAttr
, mkAttributeList
, mkBlocks
, mkCitation
[ mkAttr
, mkCell
, mkRow
, mkTableHead
, mkTableFoot
, mkInlines
, mkAttributeList
, mkCitation
, mkListAttributes
, mkRow
, mkTableFoot
, mkTableHead
, mkSimpleTable
, defun "ReaderOptions"
### liftPure id
<#> parameter peekReaderOptions "ReaderOptions|table" "opts" "reader options"
<#> parameter peekReaderOptions "ReaderOptions|table" "opts"
(T.unlines
[ "Either a table with a subset of the properties of a"
, "[[ReaderOptions]] object, or another ReaderOptions object."
, "Uses the defaults specified in the manual for all"
, "properties that are not explicitly specified. Throws an"
, "error if a table contains properties which are not present"
, "in a ReaderOptions object."
]
)
=#> functionResult pushReaderOptions "ReaderOptions" "new object"
#? "Creates a new ReaderOptions value."
#? T.unlines
[ "Creates a new ReaderOptions value."
, ""
, "Usage:"
, ""
, " -- copy of the reader options that were defined on the command line."
, " local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS)"
, " -- default reader options, but columns set to 66."
, " local short_colums_opts = pandoc.ReaderOptions {columns = 66}"
]
, defun "WriterOptions"
### liftPure id
<#> parameter peekWriterOptions "WriterOptions|table" "opts"
"writer options"
(T.unlines
[ "Either a table with a subset of the properties of a"
, "[[WriterOptions]] object, or another WriterOptions object."
, "Uses the defaults specified in the manual for all"
, "properties that are not explicitly specified. Throws an"
, "error if a table contains properties which are not present"
, "in a WriterOptions object."
])
=#> functionResult pushWriterOptions "WriterOptions" "new object"
#? "Creates a new WriterOptions value."
]
@ -260,22 +282,59 @@ functions =
(ByteStringWriter w, es) -> Left <$>
w writerOpts{ writerExtensions = es } doc)
<#> parameter peekPandoc "Pandoc" "doc" "document to convert"
<#> opt (parameter peekFlavoredFormat "string|table"
"formatspec" "format and extensions")
<#> opt (parameter peekWriterOptions "WriterOptions" "writer_options"
"writer options")
<#> opt (parameter peekFlavoredFormat "string|table" "formatspec"
(T.unlines
[ "format specification; defaults to `\"html\"`. See the"
, "documentation of [`pandoc.read`](#pandoc.read) for a complete"
, "description of this parameter."
]))
<#> opt (parameter peekWriterOptions "WriterOptions|table" "writer_options"
(T.unlines
[ "options passed to the writer; may be a WriterOptions object"
, "or a table with a subset of the keys and values of a"
, "WriterOptions object; defaults to the default values"
, "documented in the manual."
])
)
=#> functionResult (either pushLazyByteString pushText) "string"
"result document"
#? T.unlines
[ "Converts a document to the given target format."
, ""
, "Usage:"
, ""
, " local doc = pandoc.Pandoc("
, " {pandoc.Para {pandoc.Strong 'Tea'}}"
, " )"
, " local html = pandoc.write(doc, 'html')"
, " assert(html == '<p><strong>Tea</strong></p>')"
]
, defun "write_classic"
### (\doc mwopts -> runCustom (fromMaybe def mwopts) doc)
<#> parameter peekPandoc "Pandoc" "doc" "document to convert"
<#> opt (parameter peekWriterOptions "WriterOptions" "writer_options"
"writer options")
(T.unlines
[ "options passed to the writer; may be a WriterOptions object"
, "or a table with a subset of the keys and values of a"
, "WriterOptions object; defaults to the default values"
, "documented in the manual."
]))
=#> functionResult pushText "string" "rendered document"
#? (T.unlines
[ "Runs a classic custom Lua writer, using the functions defined"
, "in the current environment."
, ""
, "Usage:"
, ""
, " -- Adding this function converts a classic writer into a"
, " -- new-style custom writer."
, " function Writer (doc, opts)"
, " PANDOC_DOCUMENT = doc"
, " PANDOC_WRITER_OPTIONS = opts"
, " loadfile(PANDOC_SCRIPT_FILE)()"
, " return pandoc.write_classic(doc, opts)"
, " end"
])
]
where

79
tools/update-lua-module-docs.lua
View file

@ -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))