diff options
Diffstat (limited to 'lv2specgen')
| -rw-r--r-- | lv2specgen/DTD/xhtml-rdfa-1.dtd | 41 | ||||
| -rwxr-xr-x | lv2specgen/lv2docgen.py | 108 | ||||
| -rwxr-xr-x | lv2specgen/lv2specgen.py | 472 | ||||
| -rw-r--r-- | lv2specgen/meson.build | 44 | ||||
| l--------- | lv2specgen/style.css | 1 | ||||
| -rw-r--r-- | lv2specgen/template.html | 21 |
6 files changed, 240 insertions, 447 deletions
diff --git a/lv2specgen/DTD/xhtml-rdfa-1.dtd b/lv2specgen/DTD/xhtml-rdfa-1.dtd index 26ed117..53890bb 100644 --- a/lv2specgen/DTD/xhtml-rdfa-1.dtd +++ b/lv2specgen/DTD/xhtml-rdfa-1.dtd @@ -437,36 +437,17 @@ <!-- end of XHTML-RDFa DTD ................................................ --> <!-- ....................................................................... --> -<!-- Add xmlns attributes to validate lv2specgen output --> -<!-- This is a pretty dirty hack, but avoids needing to write a bunch of code to - mangle DTDs to appease validation --> +<!-- Hack for lv2specgen: declare prefixes for the external vocabularies used + in LV2 (most of which are generally common for RDF), so RDFa in spec pages + can use prefixed names. This glaring separation-of-concerns violation + is... not nice, but neither is diving into the horrors of custom XML DTD + validation, so here we are. +--> -<!ATTLIST html xmlns:dc CDATA #IMPLIED> -<!ATTLIST html xmlns:dct CDATA #IMPLIED> +<!ATTLIST html xmlns:dcterms CDATA #IMPLIED> +<!ATTLIST html xmlns:doap CDATA #IMPLIED> +<!ATTLIST html xmlns:foaf CDATA #IMPLIED> +<!ATTLIST html xmlns:owl CDATA #IMPLIED> <!ATTLIST html xmlns:rdf CDATA #IMPLIED> <!ATTLIST html xmlns:rdfs CDATA #IMPLIED> - -<!ATTLIST html xmlns:atom CDATA #IMPLIED> -<!ATTLIST html xmlns:bufsz CDATA #IMPLIED> -<!ATTLIST html xmlns:da CDATA #IMPLIED> -<!ATTLIST html xmlns:dman CDATA #IMPLIED> -<!ATTLIST html xmlns:ev CDATA #IMPLIED> -<!ATTLIST html xmlns:ia CDATA #IMPLIED> -<!ATTLIST html xmlns:log CDATA #IMPLIED> -<!ATTLIST html xmlns:lv2 CDATA #IMPLIED> -<!ATTLIST html xmlns:midi CDATA #IMPLIED> -<!ATTLIST html xmlns:morph CDATA #IMPLIED> -<!ATTLIST html xmlns:opts CDATA #IMPLIED> -<!ATTLIST html xmlns:param CDATA #IMPLIED> -<!ATTLIST html xmlns:patch CDATA #IMPLIED> -<!ATTLIST html xmlns:pg CDATA #IMPLIED> -<!ATTLIST html xmlns:pprops CDATA #IMPLIED> -<!ATTLIST html xmlns:pset CDATA #IMPLIED> -<!ATTLIST html xmlns:rsz CDATA #IMPLIED> -<!ATTLIST html xmlns:state CDATA #IMPLIED> -<!ATTLIST html xmlns:time CDATA #IMPLIED> -<!ATTLIST html xmlns:ui CDATA #IMPLIED> -<!ATTLIST html xmlns:umap CDATA #IMPLIED> -<!ATTLIST html xmlns:units CDATA #IMPLIED> -<!ATTLIST html xmlns:urid CDATA #IMPLIED> -<!ATTLIST html xmlns:work CDATA #IMPLIED> +<!ATTLIST html xmlns:xsd CDATA #IMPLIED> diff --git a/lv2specgen/lv2docgen.py b/lv2specgen/lv2docgen.py index 23a239d..9b1685a 100755 --- a/lv2specgen/lv2docgen.py +++ b/lv2specgen/lv2docgen.py @@ -1,82 +1,80 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- -# -# lv2docgen, a documentation generator for LV2 plugins +#!/usr/bin/env python3 + # Copyright 2012 David Robillard <d@drobilla.net> -# -# Permission to use, copy, modify, and/or distribute this software for any -# purpose with or without fee is hereby granted, provided that the above -# copyright notice and this permission notice appear in all copies. -# -# THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +# SPDX-License-Identifier: ISC import errno import os import sys -__date__ = '2012-03-27' -__version__ = '0.0.0' -__authors__ = 'David Robillard' -__license__ = 'ISC License <http://www.opensource.org/licenses/isc>' -__contact__ = 'devel@lists.lv2plug.in' +__date__ = "2012-03-27" +__version__ = "0.0.0" +__authors__ = "David Robillard" +__license__ = "ISC License <http://www.opensource.org/licenses/isc>" +__contact__ = "devel@lists.lv2plug.in" try: import rdflib except ImportError: - sys.exit('Error importing rdflib') + sys.exit("Error importing rdflib") + +doap = rdflib.Namespace("http://usefulinc.com/ns/doap#") +lv2 = rdflib.Namespace("http://lv2plug.in/ns/lv2core#") +rdf = rdflib.Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#") +rdfs = rdflib.Namespace("http://www.w3.org/2000/01/rdf-schema#") -doap = rdflib.Namespace('http://usefulinc.com/ns/doap#') -lv2 = rdflib.Namespace('http://lv2plug.in/ns/lv2core#') -rdf = rdflib.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#') -rdfs = rdflib.Namespace('http://www.w3.org/2000/01/rdf-schema#') def uri_to_path(uri): - path = uri[uri.find(':'):] + first_colon = uri.find(":") + path = uri[first_colon:] while not path[0].isalpha(): path = path[1:] return path + def get_doc(model, subject): comment = model.value(subject, rdfs.comment, None) if comment: return '<p class="content">%s</p>' % comment - return '' + return "" + def port_doc(model, port): name = model.value(port, lv2.name, None) - comment = model.value(port, rdfs.comment, None) html = '<div class="specterm"><h3>%s</h3>' % name html += get_doc(model, port) - html += '</div>' + html += "</div>" return html + def plugin_doc(model, plugin, style_uri): - uri = str(plugin) + uri = str(plugin) name = model.value(plugin, doap.name, None) - html = '''<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> + dtd = "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd" + html = """<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" %s> <html about="%s" xmlns="http://www.w3.org/1999/xhtml" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:lv2="http://lv2plug.in/ns/lv2core#" - xml:lang="en">''' % uri + xml:lang="en">""" % ( + uri, + dtd, + ) - html += '''<head> + html += """<head> <title>%s</title> <meta http-equiv="content-type" content="text/xhtml+xml; charset=utf-8" /> <meta name="generator" content="lv2docgen" /> <link href="%s" rel="stylesheet" type="text/css" /> </head> - <body>''' % (name, style_uri) + <body>""" % ( + name, + style_uri, + ) - html += ''' + html += """ <!-- HEADER --> <div id="header"> <h1 id="title">%s</h1> @@ -85,44 +83,53 @@ def plugin_doc(model, plugin, style_uri): <tr><th>Version</th><td>%s</td></tr> </table> </div> -''' % (name, uri, uri, '0.0.0') +""" % ( + name, + uri, + uri, + "0.0.0", + ) html += get_doc(model, plugin) - ports_html = '' + ports_html = "" for p in model.triples([plugin, lv2.port, None]): ports_html += port_doc(model, p[2]) if len(ports_html): - html += ''' + html += ( + """ <h2 class="sec">Ports</h2> <div class="content"> %s - </div>''' % ports_html + </div>""" + % ports_html + ) - html += ' </body></html>' + html += " </body></html>" return html -if __name__ == '__main__': - 'LV2 plugin documentation generator' + +if __name__ == "__main__": + "LV2 plugin documentation generator" if len(sys.argv) < 2: - print('Usage: %s OUTDIR FILE...' % sys.argv[0]) + print("Usage: %s OUTDIR FILE..." % sys.argv[0]) sys.exit(1) outdir = sys.argv[1] files = sys.argv[2:] model = rdflib.ConjunctiveGraph() for f in files: - model.parse(f, format='n3') + model.parse(f, format="n3") - style_uri = os.path.abspath(os.path.join(outdir, 'style.css')) + style_uri = os.path.abspath(os.path.join(outdir, "style.css")) for p in model.triples([None, rdf.type, lv2.Plugin]): plugin = p[0] html = plugin_doc(model, plugin, style_uri) path = uri_to_path(plugin) - outpath = os.path.join(outdir, path + '.html') + outpath = os.path.join(outdir, path + ".html") try: os.makedirs(os.path.dirname(outpath)) except OSError: @@ -132,7 +139,6 @@ if __name__ == '__main__': else: raise - print('Writing <%s> documentation to %s' % (plugin, outpath)) - out = open(outpath, 'w') - out.write(html) - out.close() + print("Writing <%s> documentation to %s" % (plugin, outpath)) + with open(outpath, "w") as out: + out.write(html) diff --git a/lv2specgen/lv2specgen.py b/lv2specgen/lv2specgen.py index 14c88c3..28c1500 100755 --- a/lv2specgen/lv2specgen.py +++ b/lv2specgen/lv2specgen.py @@ -1,34 +1,13 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- +#!/usr/bin/env python3 # -# lv2specgen, a documentation generator for LV2 specifications. -# Copyright (c) 2009-2014 David Robillard <d@drobilla.net> +# Copyright 2009-2022 David Robillard <d@drobilla.net> +# Copyright 2003-2008 Christopher Schmidt <crschmidt@crschmidt.net> +# Copyright 2005-2008 Uldis Bojars <uldis.bojars@deri.org> +# Copyright 2007-2008 Sergio Fernández <sergio.fernandez@fundacionctic.org> +# SPDX-License-Identifier: MIT # # Based on SpecGen: # <http://forge.morfeo-project.org/wiki_en/index.php/SpecGen> -# Copyright (c) 2003-2008 Christopher Schmidt <crschmidt@crschmidt.net> -# Copyright (c) 2005-2008 Uldis Bojars <uldis.bojars@deri.org> -# Copyright (c) 2007-2008 Sergio Fernández <sergio.fernandez@fundacionctic.org> -# -# This software is licensed under the terms of the MIT License. -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -# THE SOFTWARE. import datetime import markdown @@ -86,20 +65,13 @@ spec_pre = None spec_bundle = None specgendir = None ns_list = { + "http://purl.org/dc/terms/": "dcterms", + "http://usefulinc.com/ns/doap#": "doap", + "http://xmlns.com/foaf/0.1/": "foaf", + "http://www.w3.org/2002/07/owl#": "owl", "http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf", "http://www.w3.org/2000/01/rdf-schema#": "rdfs", - "http://www.w3.org/2002/07/owl#": "owl", "http://www.w3.org/2001/XMLSchema#": "xsd", - "http://rdfs.org/sioc/ns#": "sioc", - "http://xmlns.com/foaf/0.1/": "foaf", - "http://purl.org/dc/elements/1.1/": "dc", - "http://purl.org/dc/terms/": "dct", - "http://purl.org/rss/1.0/modules/content/": "content", - "http://www.w3.org/2003/01/geo/wgs84_pos#": "geo", - "http://www.w3.org/2004/02/skos/core#": "skos", - "http://lv2plug.in/ns/lv2core#": "lv2", - "http://usefulinc.com/ns/doap#": "doap", - "http://ontologi.es/doap-changeset#": "dcs", } rdf = rdflib.Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#") @@ -107,7 +79,6 @@ rdfs = rdflib.Namespace("http://www.w3.org/2000/01/rdf-schema#") owl = rdflib.Namespace("http://www.w3.org/2002/07/owl#") lv2 = rdflib.Namespace("http://lv2plug.in/ns/lv2core#") doap = rdflib.Namespace("http://usefulinc.com/ns/doap#") -dcs = rdflib.Namespace("http://ontologi.es/doap-changeset#") foaf = rdflib.Namespace("http://xmlns.com/foaf/0.1/") @@ -140,21 +111,20 @@ def getLiteralString(s): def isResource(n): - return type(n) == rdflib.URIRef + return isinstance(n, rdflib.URIRef) def isBlank(n): - return type(n) == rdflib.BNode + return isinstance(n, rdflib.BNode) def isLiteral(n): - return type(n) == rdflib.Literal + return isinstance(n, rdflib.Literal) def niceName(uri): - global spec_bundle if uri.startswith(spec_ns_str): - return uri[len(spec_ns_str) :] + return uri.replace(spec_ns_str, "") elif uri == str(rdfs.seeAlso): return "See also" @@ -166,8 +136,6 @@ def niceName(uri): if pref in ns_list: return ns_list.get(pref, pref) + ":" + rez.group(2) else: - print("warning: prefix %s not in ns list:" % pref) - print(ns_list) return uri @@ -239,9 +207,9 @@ def linkifyVocabIdentifiers(m, string, classlist, proplist, instalist): def prettifyHtml(m, markup, subject, classlist, proplist, instalist): # Syntax highlight all C code if have_pygments: - code_rgx = re.compile('<pre class="c-code">(.*?)</pre>', re.DOTALL) + code_re = re.compile('<pre class="c-code">(.*?)</pre>', re.DOTALL) while True: - code = code_rgx.search(markup) + code = code_re.search(markup) if not code: break match_str = xml.sax.saxutils.unescape(code.group(1)) @@ -250,15 +218,13 @@ def prettifyHtml(m, markup, subject, classlist, proplist, instalist): pygments.lexers.CLexer(), pygments.formatters.HtmlFormatter(), ) - markup = code_rgx.sub(code_str, markup, 1) + markup = code_re.sub(code_str, markup, 1) # Syntax highlight all Turtle code if have_pygments: - code_rgx = re.compile( - '<pre class="turtle-code">(.*?)</pre>', re.DOTALL - ) + code_re = re.compile('<pre class="turtle-code">(.*?)</pre>', re.DOTALL) while True: - code = code_rgx.search(markup) + code = code_re.search(markup) if not code: break match_str = xml.sax.saxutils.unescape(code.group(1)) @@ -267,7 +233,7 @@ def prettifyHtml(m, markup, subject, classlist, proplist, instalist): pygments.lexers.rdf.TurtleLexer(), pygments.formatters.HtmlFormatter(), ) - markup = code_rgx.sub(code_str, markup, 1) + markup = code_re.sub(code_str, markup, 1) # Add links to code documentation for identifiers markup = linkifyCodeIdentifiers(markup) @@ -415,8 +381,6 @@ def endProperties(first): def rdfsPropertyInfo(term, m): """Generate HTML for properties: Domain, range""" - global classranges - global classdomains doc = "" label = getLabel(m, term) @@ -570,8 +534,6 @@ def owlRestrictionInfo(term, m): def rdfsClassInfo(term, m): """Generate rdfs-type information for Classes: ranges, and domains.""" - global classranges - global classdomains doc = "" label = getLabel(m, term) @@ -768,12 +730,15 @@ def docTerms(category, list, m, classlist, proplist, instalist): doc = "" for term in list: if not term.startswith(spec_ns_str): - sys.stderr.write("warning: Skipping external term `%s'" % term) continue t = termName(m, term) curie = term.split(spec_ns_str[-1])[1] - doc += '<div class="specterm" id="%s" about="%s">' % (t, term) + if t: + doc += '<div class="specterm" id="%s" about="%s">' % (t, term) + else: + doc += '<div class="specterm" about="%s">' % term + doc += '<h3><a href="#%s">%s</a></h3>' % (getAnchor(term), curie) doc += '<span class="spectermtype">%s</span>' % category @@ -830,7 +795,7 @@ def getShortName(uri): def getAnchor(uri): uri = str(uri) if uri.startswith(spec_ns_str): - return uri[len(spec_ns_str) :].replace("/", "_") + return uri.replace(spec_ns_str, "").replace("/", "_") else: return getShortName(uri) @@ -861,7 +826,7 @@ def buildIndex(m, classlist, proplist, instalist=None): local_subclass = False for p in findStatements(m, c, rdfs.subClassOf, None): parent = str(p[2]) - if parent[0 : len(spec_ns_str)] == spec_ns_str: + if parent.startswith(spec_ns_str): local_subclass = True if local_subclass: continue @@ -930,8 +895,6 @@ def specInformation(m, ns): and proplist. Global variables classranges and classdomains are also filled as appropriate. """ - global classranges - global classdomains # Find the class information: Ranges, domains, and list of all names. classtypes = [rdfs.Class, owl.Class, rdfs.Datatype] @@ -1020,17 +983,14 @@ def specAuthors(m, subject): for d in sorted(dev): if not first: devdoc += ", " - devdoc += ( - '<span class="author" property="doap:developer">%s</span>' % d - ) + + devdoc += f'<span class="author" property="doap:developer">{d}</span>' first = False if len(dev) == 1: - doc += ( - '<tr><th class="metahead">Developer</th><td>%s</td></tr>' % devdoc - ) + doc += f'<tr><th class="metahead">Developer</th><td>{devdoc}</td></tr>' elif len(dev) > 0: doc += ( - '<tr><th class="metahead">Developers</th><td>%s</td></tr>' % devdoc + f'<tr><th class="metahead">Developers</th><td>{devdoc}</td></tr>' ) maintdoc = "" @@ -1038,95 +998,18 @@ def specAuthors(m, subject): for m in sorted(maint): if not first: maintdoc += ", " + maintdoc += ( - '<span class="author" property="doap:maintainer">%s</span>' % m + f'<span class="author" property="doap:maintainer">{m}</span>' ) first = False - if len(maint) == 1: - doc += ( - '<tr><th class="metahead">Maintainer</th><td>%s</td></tr>' - % maintdoc - ) - elif len(maint) > 0: - doc += ( - '<tr><th class="metahead">Maintainers</th><td>%s</td></tr>' - % maintdoc - ) + if len(maint): + label = "Maintainer" if len(maint) == 1 else "Maintainers" + doc += f'<tr><th class="metahead">{label}</th><td>{maintdoc}</td></tr>' return doc -def releaseChangeset(m, release, prefix=""): - changeset = findOne(m, release, dcs.changeset, None) - if changeset is None: - return "" - - entry = "" - # entry = '<dd><ul>\n' - for i in sorted(findStatements(m, getObject(changeset), dcs.item, None)): - item = getObject(i) - label = findOne(m, item, rdfs.label, None) - if not label: - print("error: dcs:item has no rdfs:label") - continue - - text = getLiteralString(getObject(label)) - if prefix: - text = prefix + ": " + text - - entry += "<li>%s</li>\n" % text - - # entry += '</ul></dd>\n' - return entry - - -def specHistoryEntries(m, subject, entries): - for r in findStatements(m, subject, doap.release, None): - release = getObject(r) - revNode = findOne(m, release, doap.revision, None) - if not revNode: - print("error: doap:release has no doap:revision") - continue - - rev = getLiteralString(getObject(revNode)) - - created = findOne(m, release, doap.created, None) - - dist = findOne(m, release, doap["file-release"], None) - if dist: - entry = '<dt><a href="%s">Version %s</a>' % (getObject(dist), rev) - else: - entry = "<dt>Version %s" % rev - # print("warning: doap:release has no doap:file-release") - - if created: - entry += " (%s)</dt>\n" % getLiteralString(getObject(created)) - else: - entry += ' (<span class="warning">EXPERIMENTAL</span>)</dt>' - - entry += "<dd><ul>\n%s" % releaseChangeset(m, release) - - if dist is not None: - entries[(getObject(created), getObject(dist))] = entry - - return entries - - -def specHistoryMarkup(entries): - if len(entries) > 0: - history = "<dl>\n" - for e in sorted(entries.keys(), reverse=True): - history += entries[e] + "</ul></dd>" - history += "</dl>\n" - return history - else: - return "" - - -def specHistory(m, subject): - return specHistoryMarkup(specHistoryEntries(m, subject, {})) - - def specVersion(m, subject): """ Return a (minorVersion, microVersion, date) tuple @@ -1222,7 +1105,6 @@ def load_tags(path, docdir): and cn.tagName == "compound" and cn.getAttribute("kind") != "page" ): - name = getChildText(cn, "name") filename = getChildText(cn, "filename") anchor = getChildText(cn, "anchor") @@ -1246,129 +1128,14 @@ def load_tags(path, docdir): return linkmap -def writeIndex(model, specloc, index_path, root_path, root_uri, online): - # Get extension URI - ext_node = model.value(None, rdf.type, lv2.Specification) - if not ext_node: - ext_node = model.value(None, rdf.type, owl.Ontology) - if not ext_node: - print("no extension found in %s" % bundle) - sys.exit(1) - - ext = str(ext_node) - - # Get version - minor = 0 - micro = 0 - try: - minor = int(model.value(ext_node, lv2.minorVersion, None)) - micro = int(model.value(ext_node, lv2.microVersion, None)) - except Exception: - print("warning: %s: failed to find version for %s" % (bundle, ext)) - - # Get date - date = None - for r in model.triples([ext_node, doap.release, None]): - revision = model.value(r[2], doap.revision, None) - if str(revision) == ("%d.%d" % (minor, micro)): - date = model.value(r[2], doap.created, None) - break - - # Verify that this date is the latest - if date is None: - print("warning: %s has no doap:created date" % ext_node) - else: - for r in model.triples([ext_node, doap.release, None]): - this_date = model.value(r[2], doap.created, None) - if this_date is None: - print( - "warning: %s has no doap:created date" - % (ext_node, minor, micro, date) - ) - continue - - if this_date > date: - print( - "warning: %s revision %d.%d (%s) is not the latest release" - % (ext_node, minor, micro, date) - ) - break - - # Get name and short description - name = model.value(ext_node, doap.name, None) - shortdesc = model.value(ext_node, doap.shortdesc, None) - - # Chop 'LV2' prefix from name for cleaner index - if name.startswith("LV2 "): - name = name[4:] - - # Find relative link target - if root_uri and ext_node.startswith(root_uri): - target = ext_node[len(root_uri) :] - else: - target = os.path.relpath(ext_node, root_path) - - if not online: - target += ".html" - - stem = os.path.splitext(os.path.basename(target))[0] - - # Specification (comment is to act as a sort key) - row = '<tr><!-- %s --><td><a rel="rdfs:seeAlso" href="%s">%s</a></td>' % ( - b, - target, - name, - ) - - # API - row += "<td>" - row += '<a rel="rdfs:seeAlso" href="../doc/html/group__%s.html">%s</a>' % ( - stem, - name, - ) - row += "</td>" - - # Description - if shortdesc: - row += "<td>" + str(shortdesc) + "</td>" - else: - row += "<td></td>" - - # Version - version_str = "%s.%s" % (minor, micro) - if minor == 0 or (micro % 2 != 0): - row += '<td><span style="color: red">' + version_str + "</span></td>" - else: - row += "<td>" + version_str + "</td>" - - # Status - deprecated = model.value(ext_node, owl.deprecated, None) - if minor == 0: - row += '<td><span class="error">Experimental</span></td>' - elif deprecated and str(deprecated[2]) != "false": - row += '<td><span class="warning">Deprecated</span></td>' - elif micro % 2 == 0: - row += '<td><span class="success">Stable</span></td>' - - row += "</tr>" - - index = open(index_path, "w") - index.write(row) - index.close() - - def specgen( specloc, - indir, + template_path, style_uri, docdir, tags, opts, instances=False, - root_link=None, - index_path=None, - root_path=None, - root_uri=None, ): """The meat and potatoes: Everything starts here.""" @@ -1377,24 +1144,24 @@ def specgen( global spec_ns_str global spec_ns global spec_pre - global ns_list - global specgendir global linkmap spec_bundle = "file://%s/" % os.path.abspath(os.path.dirname(specloc)) - specgendir = os.path.abspath(indir) # Template - temploc = os.path.join(indir, "template.html") - template = None - f = open(temploc, "r") - template = f.read() - f.close() + with open(template_path, "r") as f: + template = f.read() # Load code documentation link map from tags file linkmap = load_tags(tags, docdir) m = rdflib.ConjunctiveGraph() + + # RDFLib adds its own prefixes, so kludge around "time" prefix conflict + m.namespace_manager.bind( + "time", rdflib.URIRef("http://lv2plug.in/ns/ext/time#"), replace=True + ) + manifest_path = os.path.join(os.path.dirname(specloc), "manifest.ttl") if os.path.exists(manifest_path): m.parse(manifest_path, format="n3") @@ -1490,8 +1257,6 @@ def specgen( name = specProperty(m, spec, doap.name) title = name - if root_link: - name = '<a href="%s">%s</a>' % (root_link, name) template = template.replace("@TITLE@", title) template = template.replace("@NAME@", name) @@ -1500,15 +1265,9 @@ def specgen( ) template = template.replace("@URI@", spec) template = template.replace("@PREFIX@", spec_pre) - if spec_pre == "lv2": - template = template.replace("@XMLNS@", "") - else: - template = template.replace( - "@XMLNS@", ' xmlns:%s="%s"' % (spec_pre, spec_ns_str) - ) filename = os.path.basename(specloc) - basename = filename[0 : filename.rfind(".")] + basename = os.path.splitext(filename)[0] template = template.replace("@STYLE_URI@", style_uri) template = template.replace("@PREFIXES@", str(prefixes_html)) @@ -1518,7 +1277,6 @@ def specgen( template = template.replace("@REFERENCE@", termlist) template = template.replace("@FILENAME@", filename) template = template.replace("@HEADER@", basename + ".h") - template = template.replace("@HISTORY@", specHistory(m, spec)) mail_row = "" if "list_email" in opts: @@ -1560,14 +1318,10 @@ def specgen( template = template.replace("@DESCRIPTION@", docs) now = int(os.environ.get("SOURCE_DATE_EPOCH", time.time())) - build_date = datetime.datetime.utcfromtimestamp(now) + build_date = datetime.datetime.fromtimestamp(now, datetime.timezone.utc) template = template.replace("@DATE@", build_date.strftime("%F")) template = template.replace("@TIME@", build_date.strftime("%F %H:%M UTC")) - # Write index row - if index_path is not None: - writeIndex(m, specloc, index_path, root_path, root_uri, opts["online"]) - # Validate complete output page try: oldcwd = os.getcwd() @@ -1580,7 +1334,9 @@ def specgen( etree.XMLParser(dtd_validation=True, no_network=True), ) except Exception as e: - sys.stderr.write("error: Validation failed for %s: %s" % (specloc, e)) + sys.stderr.write( + "error: Validation failed for %s: %s\n" % (specloc, e) + ) finally: os.chdir(oldcwd) @@ -1589,10 +1345,9 @@ def specgen( def save(path, text): try: - f = open(path, "w") - f.write(text) - f.flush() - f.close() + with open(path, "w") as f: + f.write(text) + f.flush() except Exception: e = sys.exc_info()[1] print('Error writing to file "' + path + '": ' + str(e)) @@ -1628,12 +1383,57 @@ def usage(): return "Usage: %s ONTOLOGY_TTL OUTPUT_HTML [OPTION]..." % script +def _path_from_env(variable, default): + value = os.environ.get(variable) + return value if value and os.path.isabs(value) else default + + +def _paths_from_env(variable, default): + paths = [] + value = os.environ.get(variable) + if value: + paths = [p for p in value.split(os.pathsep) if os.path.isabs(p)] + + return paths if paths else default + + +def _data_dirs(): + return _paths_from_env( + "XDG_DATA_DIRS", ["/usr/local/share/", "/usr/share/"] + ) + + if __name__ == "__main__": """Ontology specification generator tool""" - indir = os.path.abspath(os.path.dirname(sys.argv[0])) - if not os.path.exists(os.path.join(indir, "template.html")): - indir = os.path.join(os.path.dirname(indir), "share", "lv2specgen") + data_dir = None + for d in _data_dirs(): + path = os.path.join(d, "lv2specgen") + if ( + os.path.exists(os.path.join(path, "template.html")) + and os.path.exists(os.path.join(path, "style.css")) + and os.path.exists(os.path.join(path, "pygments.css")) + ): + data_dir = path + break + + if data_dir: + # Use installed files + specgendir = data_dir + default_template_path = os.path.join(data_dir, "template.html") + default_style_dir = data_dir + else: + script_path = os.path.realpath(__file__) + script_dir = os.path.dirname(os.path.realpath(__file__)) + if os.path.exists(os.path.join(script_dir, "template.html")): + # Run from source repository + specgendir = script_dir + lv2_source_root = os.path.dirname(script_dir) + default_template_path = os.path.join(script_dir, "template.html") + default_style_dir = os.path.join(lv2_source_root, "doc", "style") + else: + sys.stderr.write("error: Unable to find lv2specgen data\n") + sys.exit(-2) opt = optparse.OptionParser( usage=usage(), @@ -1652,11 +1452,18 @@ if __name__ == "__main__": help="Mailing list info page address", ) opt.add_option( - "--template-dir", + "--template", type="string", - dest="template_dir", - default=indir, - help="Template directory", + dest="template", + default=default_template_path, + help="Template file for output page", + ) + opt.add_option( + "--style-dir", + type="string", + dest="style_dir", + default=default_style_dir, + help="Stylesheet directory path", ) opt.add_option( "--style-uri", @@ -1673,13 +1480,6 @@ if __name__ == "__main__": help="Doxygen output directory", ) opt.add_option( - "--index", - type="string", - dest="index_path", - default=None, - help="Index row output file", - ) - opt.add_option( "--tags", type="string", dest="tags", @@ -1687,22 +1487,6 @@ if __name__ == "__main__": help="Doxygen tags file", ) opt.add_option( - "-r", - "--root-path", - type="string", - dest="root_path", - default="", - help="Root path", - ) - opt.add_option( - "-R", - "--root-uri", - type="string", - dest="root_uri", - default="", - help="Root URI", - ) - opt.add_option( "-p", "--prefix", type="string", @@ -1722,13 +1506,6 @@ if __name__ == "__main__": dest="copy_style", help="Copy style from template directory to output directory", ) - opt.add_option( - "-o", - "--online", - action="store_true", - dest="online", - help="Generate index for online documentation", - ) (options, args) = opt.parse_args() opts = vars(options) @@ -1740,7 +1517,6 @@ if __name__ == "__main__": spec_pre = options.prefix ontology = "file:" + str(args[0]) output = args[1] - index_path = options.index_path docdir = options.docdir tags = options.tags @@ -1753,27 +1529,18 @@ if __name__ == "__main__": b = os.path.basename(outdir) if not os.access(os.path.abspath(spec), os.R_OK): - print("warning: extension %s has no %s.ttl file" % (b, b)) + sys.stderr.write("error: extension %s has no %s.ttl file\n" % (b, b)) sys.exit(1) - # Root link - root_path = opts["root_path"] - root_uri = opts["root_uri"] - root_link = os.path.join(root_path, "index.html") - # Generate spec documentation specdoc = specgen( spec, - indir, + opts["template"], opts["style_uri"], docdir, tags, opts, instances=True, - root_link=root_link, - index_path=index_path, - root_path=root_path, - root_uri=root_uri, ) # Save to HTML output file @@ -1782,7 +1549,10 @@ if __name__ == "__main__": if opts["copy_style"]: import shutil - shutil.copyfile( - os.path.join(indir, "style.css"), - os.path.join(os.path.dirname(output), "style.css"), - ) + for stylesheet in ["pygments.css", "style.css"]: + style_dir = opts["style_dir"] + output_dir = os.path.dirname(output) + shutil.copyfile( + os.path.join(style_dir, stylesheet), + os.path.join(output_dir, stylesheet), + ) diff --git a/lv2specgen/meson.build b/lv2specgen/meson.build new file mode 100644 index 0000000..69b029b --- /dev/null +++ b/lv2specgen/meson.build @@ -0,0 +1,44 @@ +# Copyright 2022 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: 0BSD OR ISC + +lv2specgen_py = files('lv2specgen.py') + +lv2_list_email = 'devel@lists.lv2plug.in' +lv2_list_page = 'http://lists.lv2plug.in/listinfo.cgi/devel-lv2plug.in' + +lv2specgen_command_prefix = [ + lv2specgen_py, + '--list-email=' + lv2_list_email, + '--list-page=' + lv2_list_page, + '--style-dir=' + lv2_source_root / 'doc' / 'style', + '--template', + files('template.html'), +] + +if is_variable('lv2_tags') + lv2specgen_command_prefix += [ + ['--tags', lv2_tags.full_path()], # TODO: Remove full_path() in meson 0.60.0 + ] +endif + +install_data( + files('lv2specgen.py'), + install_dir: get_option('bindir'), + install_mode: 'rwxr-xr-x', +) + +meson.override_find_program('lv2specgen.py', lv2specgen_py) + +install_data( + files( + '../doc/style/pygments.css', + '../doc/style/style.css', + 'template.html', + ), + install_dir: get_option('datadir') / 'lv2specgen', +) + +install_subdir( + 'DTD', + install_dir: get_option('datadir') / 'lv2specgen', +) diff --git a/lv2specgen/style.css b/lv2specgen/style.css deleted file mode 120000 index f320096..0000000 --- a/lv2specgen/style.css +++ /dev/null @@ -1 +0,0 @@ -../doc/style.css
\ No newline at end of file diff --git a/lv2specgen/template.html b/lv2specgen/template.html index ed9d6fb..dcc2759 100644 --- a/lv2specgen/template.html +++ b/lv2specgen/template.html @@ -2,12 +2,13 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> <html about="@URI@" xmlns="http://www.w3.org/1999/xhtml" - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:dct="http://purl.org/dc/terms/" + xmlns:dcterms="http://purl.org/dc/terms/" + xmlns:doap="http://usefulinc.com/ns/doap#" + xmlns:foaf="http://xmlns.com/foaf/0.1/" + xmlns:owl="http://www.w3.org/2002/07/owl#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" - xmlns:lv2="http://lv2plug.in/ns/lv2core#" - @XMLNS@ + xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xml:lang="en"> <head> <title>@TITLE@</title> @@ -28,7 +29,6 @@ <table id="meta"> <tr><th>ID</th><td><a href="@URI@">@URI@</a></td></tr> <tr><th>Version</th><td>@VERSION@</td></tr> - <tr><th>Date</th><td>@DATE@</td></tr> @MAIL@ @AUTHORS@ </table> @@ -42,7 +42,6 @@ <ul id="contents"> <!-- <li><a href="#sec-description">Description</a></li> --> <li><a href="#sec-index">Index</a></li> - <li><a href="#sec-history">History</a></li> @CONTENT_LINKS@ </ul> </div> @@ -61,12 +60,6 @@ @REFERENCE@ </div> - <!-- HISTORY --> - <h2 id="sec-history">History</h2> - <div class="section"> - @HISTORY@ - </div> - <!-- FOOTER --> <div id="footer"> <div> @@ -77,12 +70,12 @@ </div> <div> Valid - <a about="" rel="dct:conformsTo" resource="http://www.w3.org/TR/rdfa-syntax" + <a about="" rel="dcterms:conformsTo" resource="http://www.w3.org/TR/rdfa-syntax" href="http://validator.w3.org/check?uri=referer"> XHTML+RDFa </a> and - <a about="" rel="dct:conformsTo" resource="http://www.w3.org/TR/CSS2" + <a about="" rel="dcterms:conformsTo" resource="http://www.w3.org/TR/CSS2" href="http://jigsaw.w3.org/css-validator/check/referer"> CSS </a> |