aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2020-03-22 19:28:40 +0100
committerDavid Robillard <d@drobilla.net>2020-03-28 17:10:05 +0100
commitdbeba1eef8bd7c5210d661fe768515d485ab5aad (patch)
tree1b66a5da0c3c471cd18be3d2abe26475ddb10d20
parent59c3df529e9216eaeb7407980d9d580f8ba283dd (diff)
downloadlv2-dbeba1eef8bd7c5210d661fe768515d485ab5aad.tar.xz
lv2specgen: Add support for Markdown documentation
-rwxr-xr-xlv2specgen/lv2specgen.py72
-rw-r--r--lv2specgen/template.html2
2 files changed, 57 insertions, 17 deletions
diff --git a/lv2specgen/lv2specgen.py b/lv2specgen/lv2specgen.py
index 24cacd2..f3f39b6 100755
--- a/lv2specgen/lv2specgen.py
+++ b/lv2specgen/lv2specgen.py
@@ -31,6 +31,8 @@
# THE SOFTWARE.
import datetime
+import markdown
+import markdown.extensions
import optparse
import os
import re
@@ -311,20 +313,61 @@ def prettifyHtml(m, markup, subject, classlist, proplist, instalist):
return markup
-def getComment(m, urinode, classlist, proplist, instalist):
- c = findOne(m, urinode, lv2.documentation, None)
+def formatDoc(m, urinode, literal, classlist, proplist, instalist):
+ string = getLiteralString(literal)
+
+ if literal.datatype == lv2.Markdown:
+ ext = ["markdown.extensions.codehilite",
+ "markdown.extensions.tables",
+ "markdown.extensions.def_list"]
+
+ doc = markdown.markdown(string, extensions=ext)
+
+ # Hack to make tables valid XHTML Basic 1.1
+ for tag in ['thead', 'tbody']:
+ doc = doc.replace('<%s>\n' % tag, '')
+ doc = doc.replace('</%s>\n' % tag, '')
+
+ return prettifyHtml(m, doc, urinode, classlist, proplist, instalist)
+ else:
+ doc = xml.sax.saxutils.escape(string)
+ doc = linkifyCodeIdentifiers(doc)
+ doc = linkifyVocabIdentifiers(m, doc, classlist, proplist, instalist)
+ return '<p>%s</p>' % doc
+
+
+def getComment(m, subject, classlist, proplist, instalist):
+ c = findOne(m, subject, rdfs.comment, None)
if c:
- markup = getLiteralString(getObject(c))
- markup = prettifyHtml(m, markup, urinode, classlist, proplist, instalist)
- return markup
+ comment = getObject(c)
+ return formatDoc(m, subject, comment, classlist, proplist, instalist)
+
+ return ''
- c = findOne(m, urinode, rdfs.comment, None)
- if not c:
- return ''
- comment = getObject(c)
+def getDetailedDocumentation(m, subject, classlist, proplist, instalist):
+ markup = ''
+
+ d = findOne(m, subject, lv2.documentation, None)
+ if d:
+ doc = getObject(d)
+ if doc.datatype == lv2.Markdown:
+ markup += formatDoc(m, subject, doc, classlist, proplist, instalist)
+ else:
+ html = getLiteralString(doc)
+ markup += prettifyHtml(m, html, subject, classlist, proplist, instalist)
+
+ return markup
- return '<p>%s</p>' % xml.sax.saxutils.escape(getLiteralString(comment))
+
+def getFullDocumentation(m, subject, classlist, proplist, instalist):
+ # Use rdfs:comment for first summary line
+ markup = getComment(m, subject, classlist, proplist, instalist)
+
+ # Use lv2:documentation for further details
+ markup += getDetailedDocumentation(m, subject, classlist, proplist, instalist)
+
+ return markup
def getProperty(val, first=True):
@@ -653,7 +696,7 @@ def docTerms(category, list, m, classlist, proplist, instalist):
doc += '<h4><a href="#%s">%s</a></h4>' % (getAnchor(term), curie)
label = getLabel(m, term)
- comment = getComment(m, term, classlist, proplist, instalist)
+ comment = getFullDocumentation(m, term, classlist, proplist, instalist)
is_deprecated = isDeprecated(m, term)
doc += '<div class="spectermbody">'
@@ -1325,11 +1368,8 @@ def specgen(specloc, indir, style_uri, docdir, tags, opts, instances=False, root
template = template.replace('@CONTENT_LINKS@', content_links)
- comment = getComment(m, rdflib.URIRef(spec_url), classlist, proplist, instalist)
- if comment != '':
- template = template.replace('@COMMENT@', comment)
- else:
- template = template.replace('@COMMENT@', '')
+ docs = getDetailedDocumentation(m, rdflib.URIRef(spec_url), classlist, proplist, instalist)
+ template = template.replace('@DESCRIPTION@', docs)
now = int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
build_date = datetime.datetime.utcfromtimestamp(now)
diff --git a/lv2specgen/template.html b/lv2specgen/template.html
index a459a94..059a599 100644
--- a/lv2specgen/template.html
+++ b/lv2specgen/template.html
@@ -49,7 +49,7 @@
<hr class="contentssep" />
<!-- DESCRIPTION -->
- <div class="section">@COMMENT@</div>
+ <div class="section">@DESCRIPTION@</div>
<!-- REFERENCE -->
<h2 class="sec" id="sec-reference">Reference</h2>