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

Closes #10999.

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

3 files changed, 46 insertions, 9 deletions

diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs
index 412131560..7d0c76b80 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs
@@ -104,8 +104,9 @@ insert = defun "insert"
           setMediaBag $ MB.insertMedia fp mmime contents mb
           return (Lua.NumResults 0))
   <#> stringParam "filepath" "filename and path relative to the output folder."
-  <#> opt (textParam "mimetype"
-           "the item's MIME type; omit if unknown or unavailable.")
+  <#> parameter (Lua.peekNilOr Lua.peekText) "string|nil" "mimetype"
+        "the item's MIME type; use `nil` if the MIME type is\
+        \ unknown or unavailable."
   <#> parameter Lua.peekLazyByteString "string" "contents"
         "the binary contents of the file."
   =#> []
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Path.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Path.hs
index efe00e03c..9334a2252 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Path.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Path.hs
@@ -3,7 +3,7 @@
 {-# LANGUAGE TypeApplications    #-}
 {- |
    Module      : Text.Pandoc.Lua.Module.Path
-   Copyright   : © 2019-2024 Albert Krewinkel
+   Copyright   : © 2019-2026 Albert Krewinkel
    License     : GNU GPL, version 2 or above
 
    Maintainer  : Albert Krewinkel <[email protected]>
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 d4b7cea08..a5a6bde8b 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs
@@ -4,7 +4,7 @@
 {-# LANGUAGE TypeApplications    #-}
 {- |
    Module      : Text.Pandoc.Lua.Module.Utils
-   Copyright   : Copyright © 2017-2026 Albert Krewinkel
+   Copyright   : © 2017-2026 Albert Krewinkel
    License     : GNU GPL, version 2 or above
 
    Maintainer  : Albert Krewinkel <[email protected]>
@@ -19,6 +19,7 @@ module Text.Pandoc.Lua.Module.Utils
 
 import Control.Applicative ((<|>))
 import Control.Monad ((<$!>))
+import Control.Monad.Except (MonadError (throwError))
 import Crypto.Hash (hashWith, SHA1(SHA1))
 import Data.Data (showConstr, toConstr)
 import Data.Default (def)
@@ -28,12 +29,17 @@ import HsLua as Lua
 import HsLua.Module.Version (peekVersionFuzzy, pushVersion)
 import Text.Pandoc.Citeproc (getReferences, processCitations)
 import Text.Pandoc.Definition
-import Text.Pandoc.Error (PandocError)
+import Text.Pandoc.Error (PandocError (PandocLuaError))
 import Text.Pandoc.Filter (applyJSONFilter)
+import Text.Pandoc.Format (FlavoredFormat (formatName), parseFlavoredFormat)
+import Text.Pandoc.Lua.Documentation (renderDocumentation)
 import Text.Pandoc.Lua.Filter (runFilterFile')
 import Text.Pandoc.Lua.Marshal.AST
+import Text.Pandoc.Lua.Marshal.Format (peekFlavoredFormat)
 import Text.Pandoc.Lua.Marshal.Reference
 import Text.Pandoc.Lua.PandocLua (PandocLua (unPandocLua))
+import Text.Pandoc.Options (WriterOptions (writerExtensions))
+import Text.Pandoc.Writers (Writer (..), getWriter)
 
 import qualified Data.Map as Map
 import qualified Data.Text as T
@@ -52,6 +58,7 @@ documentedModule = defmodule "pandoc.utils"
   `withFunctions`
     [ blocks_to_inlines `since` v[2,2,3]
     , citeproc          `since` v[2,19,1]
+    , documentation     `since` v[3,8,4]
     , equals            `since` v[2,5]
     , from_simple_table `since` v[2,11]
     , make_sections     `since` v[2,8]
@@ -67,8 +74,7 @@ documentedModule = defmodule "pandoc.utils"
 
     , defun "Version"
       ### liftPure (id @Version)
-      <#> parameter peekVersionFuzzy
-            "version string, list of integers, or integer"
+      <#> parameter peekVersionFuzzy "Version|string|{integer,...}|number"
             "v" "version description"
       =#> functionResult pushVersion "Version" "new Version object"
       #? "Creates a Version object."
@@ -125,6 +131,35 @@ citeproc = defun "citeproc"
       , "    end"
       ]
 
+documentation :: DocumentedFunction PandocError
+documentation = defun "documentation"
+  ### (\idx mformat -> do
+          docobj <- getdocumentation idx >>= \case
+            TypeNil -> fail "Undocumented object"
+            _ -> forcePeek $ peekDocumentationObject top
+          let blocks = renderDocumentation docobj
+          if maybe mempty formatName mformat == "blocks"
+            then pure . Left $ B.toList blocks
+            else unPandocLua $ do
+              flvrd <- maybe (parseFlavoredFormat "ansi") pure mformat
+              getWriter flvrd >>= \case
+                (TextWriter w, es) -> Right <$>
+                  w def{ writerExtensions = es } (B.doc blocks)
+                _ -> throwError $ PandocLuaError
+                  "ByteString writers are not supported here.")
+  <#> parameter pure "any" "object" "Retrieve documentation for this object"
+  <#> opt (parameter peekFlavoredFormat "string|table" "format"
+            "result format; defaults to `'ansi'`")
+  =#> functionResult (either pushBlocks pushText) "string|Blocks"
+        "rendered documentation"
+  #? "Return the documentation for a function or module defined by pandoc.\
+     \ Throws an error if there is no documentation for the given object.\n\
+     \\n\
+     \The result format can be any textual format accepted by `pandoc.write`,\
+     \ and the documentation will be returned in that format.\
+     \ Additionally, the special format `blocks` is accepted, in which case\
+     \ the documentation is returned as [[Blocks]]."
+
 equals :: LuaError e => DocumentedFunction e
 equals = defun "equals"
   ### equal
@@ -205,7 +240,7 @@ normalize_date :: DocumentedFunction e
 normalize_date = defun "normalize_date"
   ### liftPure Shared.normalizeDate
   <#> parameter peekText "string" "date" "the date string"
-  =#> functionResult (maybe pushnil pushText) "string or nil"
+  =#> functionResult (maybe pushnil pushText) "string|nil"
         "normalized date, or nil if normalization failed."
   #? T.unwords
   [ "Parse a date and convert (if possible) to \"YYYY-MM-DD\" format. We"
@@ -320,7 +355,8 @@ stringify = defun "stringify"
          , (fmap (const "") . peekAttr)
          , (fmap (const "") . peekListAttributes)
          ] idx)
-  <#> parameter pure "AST element" "element" "some pandoc AST element"
+  <#> parameter pure "Pandoc|Block|Inline|Caption|Cell|MetaValue"
+        "element" "some pandoc AST element"
   =#> functionResult pushText "string"
         "A plain string representation of the given element."
   #? T.unlines