create function documentation in markdown based on xqDoc annotations

xqdoc-to-markdown.xq

xquery version "3.1";

(:~ 
: This module generates the function documentation for the xQuery modules, in the context of eXist-db.
:    
: @author Duncan Paterson
: @version 0.7
: 
: @return  func-doc.md:)

(: set app and config to your repo :)
import module namespace app="http://exist-db.org/apps/*YOUR-APP-NAME*/templates" at "app.xql";
import module namespace config="http://exist-db.org/apps/*YOUR-APP-NAME*/config" at "config.xqm";
import module namespace docs="http://exist-db.org/xquery/docs" at "/db/apps/fundocs/modules/scan.xql";

declare namespace xqdoc="http://www.xqdoc.org/1.0";

(: add modules as desired :)
declare variable $modules := (xs:anyURI($config:app-root || "/modules" || " app.xql"),  
    xs:anyURI($config:app-root || "/modules" || "config.xqm"), 
    xs:anyURI($config:app-root || "/modules" || "xqdoc-to-markdown.xqm"));
    
declare variable $docs := $modules ! inspect:inspect-module(.);

declare variable $preface := normalize-space('This document contains ...');

declare function local:report-transform ($nodes as node()*) as item()* {
(:~ 
: This is the main transformation from xml into md.
:
: @param $node expects a node from the xqDoc report generated by exist. 
: @see http://xqdoc.org
: @see http://www.exist-db.org/exist/apps/doc/xqdoc.xml?q=xqDoc&field=all&id=D2.2.2#D2.2.2
:)

for $n in $nodes
return
    switch(local-name($n))
        case "module" return concat('*   *Module Uri:* ', '[', data($n/@uri), '](', data($n/@location), ')')
        case "variable" return '*   *$' || data($n/@name) || '* - *missing description*'
        case "xxx" return '*   ' || $n || '
'
        case "function" return '```xQuery' || '
' || 'declare function ' || data($n/@name) || 
            "(" || string-join(
                 for $param in $n/argument
                 return
                     "$" || $param/@var/string()  || " as " || $param/@type/string() || docs:cardinality($param/@cardinality),
                 ", ") || 
             ")" || " as " || $n/returns/@type/string() || docs:cardinality($n/returns/@cardinality) || '
' || '```'
        case "argument" return '*   ' || '$' ||  data($n/@var) || ' - ' || $n/text()
        case "returns" return '*  ' || $n/text()
        case "description" return normalize-space($n/string())
        case "calls" return 
            for $c in $n/function
            return
                '``' || data($c/@module) || '``' || '|[' || data($c/@name) || '](#' || substring-after(data($c/@name), ':') || ')'
        case "annotation" return ()
        case "value" return () 
        case "xml" return ()
        case "version" return '*   Version: ' || normalize-space($n/text())
        case "author" return '*   Author: ' || normalize-space($n/text())
        case "since" return '*   Since: ' || normalize-space($n/text())
        case "control" return ()
        case "signature" return $n/text()
        case "deprecated" return '*   Depreceated:' || normalize-space($n/text())
        case "see" return '*   [see](' || normalize-space($n/text()) || ')
'
    default return ()
};


(:~
: Read the xqDoc annotation of a module and stores a markdown version in the doc folder.
:
: @param $modules the xQuery modules containing the annotation. 
:
: @return func-doc.md:)

(:  H1 Heading  :)
    ('# Function Documentation' || '
' || 
    $preface || '
' ||
    '
' ||'## Contents',
    
(:  ToC  :)
    for $toc in $docs
    let $toc-short := substring-before(substring-after(data($toc//@location), $global:modules), '.')
    return 
        ('*   [' || $toc-short || '](#' || $toc-short || '-module)'), '
',

    
    for $doc in $docs
    let $module-short := substring-before(substring-after(data($doc//@location), $global:modules), '.')
    return
        ('## ' || $module-short ||' Module',
        local:report-transform($doc[.]),
        
        if ($doc/description)
        then ('
' || '### Module Description',
                local:report-transform($doc/description),
                local:report-transform($doc/author),
                local:report-transform($doc/version),
                local:report-transform($doc/since),
                local:report-transform($doc/depreceated),
                local:report-transform($doc/see))
        else (),
    
(:  Variables  :)
        if ($doc/variable)
        then ('
' || '### Variables')
        else (),
    
    (: the table for variable calls is currently empty see    :)
        for $v in $doc/variable
            return
                (local:report-transform($v),
    
                if ($v/calls)
                then ('
' || '#### Internal Functions that reference this Variable' || '
' ||
                      '*Module URI*|*Function Name*' || '
'|| ':----|:----' ,
                        for $c in $v/calls 
                        return
                            local:report-transform($c))
                else()),
    
(:  Functions :)
        if ($doc/function)
        then ('
' || '### Function Summary')
        else (),
        
        if (count($doc/function) < 3)
        then ()
        else ('#### Contents' || '&#xa;',
            for $c in $doc/function
            return
                '*   [' || data($c/@name) || '](#' || substring-after(data($c/@name), ':') || ')'),
    
        for $f in $doc/function
        return
        ('&#xa;' || '#### ' || substring-after(data($f/@name), ':'),
    
        local:report-transform($f),
    
        if ($f/description)
        then ('&#xa;' || '##### Function Detail',
                local:report-transform($f/description))
        else (),
    
        if ($f/argument)
        then ('&#xa;' || '##### Parameters',
                local:report-transform($f/argument))
        else (),
    
        if ($f/returns)
        then ('&#xa;' || '##### Returns',
                local:report-transform($f/returns))
        else(),
    
        if ($f/calls)
        then ('&#xa;' || '##### External Functions that are used by this Function' || '&#xa;' ||
              '*Module URI*|*Function Name*' || '&#xa;' || ':----|:----',
                for $c in $f/calls 
                return
                    local:report-transform($c))
        else()) 
    , '&#xa;')
    )