Last active
August 22, 2020 23:01
-
-
Save duncdrum/bef59dac72cde0e3d8b3c4c71b8c62b2 to your computer and use it in GitHub Desktop.
create function documentation in markdown based on xqDoc annotations
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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' || '
', | |
for $c in $doc/function | |
return | |
'* [' || data($c/@name) || '](#' || substring-after(data($c/@name), ':') || ')'), | |
for $f in $doc/function | |
return | |
('
' || '#### ' || substring-after(data($f/@name), ':'), | |
local:report-transform($f), | |
if ($f/description) | |
then ('
' || '##### Function Detail', | |
local:report-transform($f/description)) | |
else (), | |
if ($f/argument) | |
then ('
' || '##### Parameters', | |
local:report-transform($f/argument)) | |
else (), | |
if ($f/returns) | |
then ('
' || '##### Returns', | |
local:report-transform($f/returns)) | |
else(), | |
if ($f/calls) | |
then ('
' || '##### External Functions that are used by this Function' || '
' || | |
'*Module URI*|*Function Name*' || '
' || ':----|:----', | |
for $c in $f/calls | |
return | |
local:report-transform($c)) | |
else()) | |
, '
') | |
) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment