aboutsummaryrefslogtreecommitdiffstats
path: root/lv2specgen
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2010-11-26 20:25:02 +0000
committerDavid Robillard <d@drobilla.net>2010-11-26 20:25:02 +0000
commite0c4fb1bc1c66e5655a41ddcbfaafb07e32b93a2 (patch)
treea73d27c9839bd99ef8e14ac3efec8d59d21c756d /lv2specgen
parenta31c23155b8b1902f70a63a12d7c09822dacda04 (diff)
downloadlv2-e0c4fb1bc1c66e5655a41ddcbfaafb07e32b93a2.tar.xz
Mark up documentation with lv2:documentation as per discussion on lv2-dev.
Use unified lv2plug.in style for ontology documentation.
Diffstat (limited to 'lv2specgen')
-rwxr-xr-xlv2specgen/lv2specgen.py104
-rw-r--r--lv2specgen/template.html41
2 files changed, 81 insertions, 64 deletions
diff --git a/lv2specgen/lv2specgen.py b/lv2specgen/lv2specgen.py
index 8fc1f93..914b774 100755
--- a/lv2specgen/lv2specgen.py
+++ b/lv2specgen/lv2specgen.py
@@ -2,7 +2,7 @@
# -*- coding: utf-8 -*-
#
# lv2specgen, an LV2 extension specification page generator
-# Copyright (c) 2009 David Robillard <d@drobilla.net>
+# Copyright (c) 2009-2010 David Robillard <d@drobilla.net>
#
# Based on SpecGen:
# <http://forge.morfeo-project.org/wiki_en/index.php/SpecGen>
@@ -41,6 +41,7 @@ import sys
import datetime
import re
import urllib
+import xml.sax.saxutils
try:
import RDF
@@ -85,6 +86,7 @@ lv2 = RDF.NS('http://lv2plug.in/ns/lv2core#')
doap = RDF.NS('http://usefulinc.com/ns/doap#')
foaf = RDF.NS('http://xmlns.com/foaf/0.1/')
+doc_base = '.'
def niceName(uri):
regexp = re.compile( "^(.*[/#])([^/#]+)$" )
@@ -102,20 +104,39 @@ def return_name(m, urinode):
"Trims the namespace out of a term to give a name to the term."
return str(urinode.uri).replace(spec_ns_str, "")
-
-def get_rdfs(m, urinode):
- "Returns label and comment given an RDF.Node with a URI in it"
- comment = ''
- label = ''
- if (type(urinode)==str):
+def getLabel(m, urinode):
+ if (type(urinode) == str):
urinode = RDF.Uri(urinode)
l = m.find_statements(RDF.Statement(urinode, rdfs.label, None))
if l.current():
- label = l.current().object.literal_value['string']
+ return l.current().object.literal_value['string']
+ else:
+ return ''
+
+def getComment(m, urinode):
+ if (type(urinode) == str):
+ urinode = RDF.Uri(urinode)
+ c = m.find_statements(RDF.Statement(urinode, lv2.documentation, None))
+ if c.current():
+ markup = c.current().object.literal_value['string']
+
+ # Replace urn:struct links with links to code documentation
+ matches = re.findall('href="urn:struct:([^"]*)"', markup)
+ if matches:
+ for match in matches:
+ struct_uri = os.path.join(doc_base, 'ns', 'doc', 'html',
+ 'struct' + match.replace('_', '__') + '.html')
+ markup = markup.replace('href="urn:struct:' + match + '"',
+ 'href="' + struct_uri + '"')
+
+ return markup
+
c = m.find_statements(RDF.Statement(urinode, rdfs.comment, None))
if c.current():
- comment = c.current().object.literal_value['string']
- return label, comment
+ text = c.current().object.literal_value['string']
+ return xml.sax.saxutils.escape(text)
+
+ return ''
def owlVersionInfo(m):
@@ -242,12 +263,12 @@ def rdfsClassInfo(term,m):
doc += '<dt>Restriction on property %s</dt>\n' % getTermLink(onProp.uri)
doc += '<dd class="restriction">\n'
if comment != None:
- doc += "<p>%s</p>\n" % comment
+ doc += "<span>%s</span>\n" % comment.literal_value['string']
prop_str = ''
for p in m.find_statements(RDF.Statement(r, None, None)):
if p.predicate != owl.onProperty and p.predicate != rdfs.comment and not(
- p.predicate == rdf.type and p.object == owl.Restriction):
+ p.predicate == rdf.type and p.object == owl.Restriction) and p.predicate != lv2.documentation:
if p.object.is_resource():
prop_str += '\n<dt>%s</dt><dd>%s</dd>\n' % (
getTermLink(p.predicate.uri), getTermLink(p.object.uri))
@@ -279,7 +300,7 @@ def rdfsClassInfo(term,m):
def isSpecial(pred):
"""Return True if the predicate is "special" and shouldn't be emitted generically"""
- return pred == rdf.type or pred == rdfs.range or pred == rdfs.domain or pred == rdfs.label or pred == rdfs.comment or pred == rdfs.subClassOf
+ return pred in [rdf.type, rdfs.range, rdfs.domain, rdfs.label, rdfs.comment, rdfs.subClassOf, lv2.documentation]
def blankNodeDesc(node,m):
@@ -399,22 +420,21 @@ def docTerms(category, list, m):
doc += """<div class="specterm" id="%s" about="%s">\n<h3>%s <a href="%s">%s</a></h3>\n""" % (t, term_uri, category, term_uri, curie)
- label, comment = get_rdfs(m, term)
+ label = getLabel(m, term)
+ comment = getComment(m, term)
+
if label!='' or comment != '':
doc += '<div class="description">'
+
if label!='':
doc += "<div property=\"rdfs:label\" class=\"label\">%s</div>" % label
+
if comment!='':
- comment = comment.replace('\n\n', '<br /><br />')
- matches = re.findall('href="urn:struct:([^"]*)"', comment)
- if matches:
- for match in matches:
- struct_uri = "../../doc/html/struct" + match.replace('_', '__') + '.html'
- comment = comment.replace('href="urn:struct:' + match + '"',
- 'href="' + struct_uri + '"')
doc += "<div property=\"rdfs:comment\">%s</div>" % comment
+
if label!='' or comment != '':
doc += "</div>"
+
terminfo = ""
if category=='Property':
terminfo += owlInfo(term,m)
@@ -628,7 +648,7 @@ def specgen(specloc, docdir, template, instances=False, mode="spec"):
global spec_ns
global spec_pre
global ns_list
-
+
m = RDF.Model()
p = RDF.Parser(name="guess")
try:
@@ -713,7 +733,7 @@ def specgen(specloc, docdir, template, instances=False, mode="spec"):
template = template.replace('@MAIL@', 'devel@lists.lv2plug.in')
revision = specRevision(m, spec_url) # (revision, date)
- if revision:
+ if revision and revision[0] != '0':
template = template.replace('@REVISION@', revision[0] + " (" + revision[1] + ")")
else:
template = template.replace('@REVISION@', '<span style="color: red; font-weight: bold">EXPERIMENTAL</span>')
@@ -726,7 +746,7 @@ def specgen(specloc, docdir, template, instances=False, mode="spec"):
release_name = "lv2-" + basename
if basename == "lv2":
release_name = "lv2core"
- other_files += '<li><a href="http://lv2plug.in/spec/%s-%s.0.tar.gz">Release</a> (<a href="http://lv2plug.in/spec">all releases</a>)</li>\n' % (release_name, revision[0])
+ other_files += '<li><a href="http://lv2plug.in/spec/%s-%s.tar.gz">Release</a> (<a href="http://lv2plug.in/spec">all releases</a>)</li>\n' % (release_name, revision[0])
if os.path.exists(os.path.abspath(header_path)):
other_files += '<li><a href="' + docdir + '/html/%s">Header Documentation</a></li>\n' % (
basename + '_8h.html')
@@ -737,16 +757,19 @@ def specgen(specloc, docdir, template, instances=False, mode="spec"):
see_also_files = specProperties(m, spec_url, rdfs.seeAlso)
for f in see_also_files:
- other_files += '<li><a href="%s">%s</a></li>' % (f, f)
+ uri = str(f.uri)
+ if uri[0:5] == 'file:':
+ uri = uri[5:]
+
+ other_files += '<li><a href="%s">%s</a></li>' % (uri, uri)
template = template.replace('@FILES@', other_files);
- comment = specProperty(m, spec_url, rdfs.comment)
- if not comment:
- comment = specProperty(m, spec_url, doap.shortdesc)
- #template = template.replace('@COMMENT@', '<p>' + comment.strip().replace('\n\n', '</p><p>') + '</p>')
- template = template.replace('@COMMENT@', comment.strip().replace('\n\n', '<br /><br />'))
- #template = template.replace('@COMMENT@', comment)
+ comment = getComment(m, spec_url)
+ if comment != '':
+ template = template.replace('@COMMENT@', comment)
+ else:
+ template = template.replace('@COMMENT@', '')
template = template.replace('@TIME@', datetime.datetime.utcnow().strftime('%F %H:%M UTC'))
@@ -800,7 +823,7 @@ def usage():
TEMPLATE : HTML template path
STYLE : CSS style path
OUTPUT : HTML output path
- DOCDIR : Doxygen documentation directory
+ BASE : Documentation output base URI
Optional flags:
-i : Document class/property instances (disabled by default)
@@ -846,22 +869,17 @@ if __name__ == "__main__":
template = template.replace('@FOOTER@', footer)
# Style
- styleloc = args[2]
- style = ''
- try:
- f = open(styleloc, "r")
- style = f.read()
- except Exception, e:
- print "Error reading from style \"" + styleloc + "\": " + str(e)
- usage()
-
- template = template.replace('@STYLE@', style)
+ style_uri = args[2]
# Destination
dest = args[3]
# Doxygen documentation directory
- docdir = args[4]
+ doc_base = args[4]
+
+ template = template.replace('@STYLE_URI@', os.path.join(doc_base, style_uri))
+
+ docdir = os.path.join(doc_base, 'ns', 'doc')
# Flags
instances = False
diff --git a/lv2specgen/template.html b/lv2specgen/template.html
index 3f4cff4..d4d76e0 100644
--- a/lv2specgen/template.html
+++ b/lv2specgen/template.html
@@ -12,32 +12,31 @@
<title>@NAME@</title>
<meta http-equiv="content-type" content="text/xhtml+xml; charset=utf-8" />
<meta name="generator" content="lv2specgen" />
- <style type="text/css">
-@STYLE@
- </style>
+ <link href="@STYLE_URI@" rel="stylesheet" type="text/css" />
</head>
<body>
- <h1 id="title">@NAME@</h1>
- <div class="meta">
- <table>
- <tr><th class="metahead">URI</th><td><a href="@URI@">@URI@</a></td></tr>
- <tr><th class="metahead">Revision</th><td>@REVISION@</td></tr>
- <tr><th class="metahead">Namespaces</th><td>@PREFIXES@</td></tr>
- @AUTHORS@
- </table>
+ <div id="titleheader">
+ <h1 id="title">@NAME@</h1>
+ <div class="meta">
+ <table>
+ <tr><th class="metahead">URI</th><td><a href="@URI@">@URI@</a></td></tr>
+ <tr><th class="metahead">Revision</th><td>@REVISION@</td></tr>
+ <tr><th class="metahead">Namespaces</th><td>@PREFIXES@</td></tr>
+ @AUTHORS@
+ </table>
+ </div>
</div>
-
<!-- META -->
<div class="content">
- <p>This document describes <a href="@URI@">@NAME@</a>,
- an <a href="http://lv2plug.in/">LV2</a> related specification.
- Comments are welcome, please direct discussion to <a
+ <p>This document is generated from <a href="@FILENAME@">@FILENAME@</a>, which
+ describes <a href="@URI@">@NAME@</a> (an <a href="http://lv2plug.in/">LV2</a>
+ specification). Comments are welcome, please direct discussion to <a
href="mailto:@MAIL@">@MAIL@</a>.</p>
</div>
- <h2 id="contents">Contents</h2>
+ <h2 class="sec" id="contents">Contents</h2>
<div class="content">
<h3>This Document</h3>
<ol id="toc">
@@ -55,13 +54,13 @@
<!-- DESCRIPTION -->
- <h2 id="sec-description">1. Description</h2>
+ <h2 class="sec" id="sec-description">1. Description</h2>
<div class="content">@COMMENT@</div>
<!-- INDEX -->
- <h2 id="sec-index">2. Index</h2>
+ <h2 class="sec" id="sec-index">2. Index</h2>
<div class="content">
@INDEX@
</div>
@@ -69,14 +68,14 @@
<!-- REFERENCE -->
- <h2 id="sec-documentation">3. Documentation</h2>
+ <h2 class="sec" id="sec-documentation">3. Documentation</h2>
<div class="content">
@REFERENCE@
</div>
<!-- REFERENCES -->
- <h2 id="sec-references">4. References</h2>
+ <h2 class="sec" id="sec-references">4. References</h2>
<div class="content">
<dl>
<dt class="label" id="ref-rfc2119">IETF RFC 2119</dt>
@@ -92,7 +91,7 @@
<!-- FOOTER -->
- <div class="footer">
+ <div id="footer">
<span class="footer-text">Generated on @TIME@ from <a href="./@FILENAME@" class="footer-text">@FILENAME@</a> by <a href="http://drobilla.net/software/lv2specgen" class="footer-text">lv2specgen</a></span>
@FOOTER@
</div>