From 68a4dc89f5e00aa6e2780f4f96011b92961b7a80 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Tue, 25 Nov 2014 00:23:48 -0500 Subject: Single-page API documentation with unified style. --- lv2specgen/lv2specgen.py | 132 ++++++++++++++++++++++++++++------------------- lv2specgen/template.html | 2 +- 2 files changed, 80 insertions(+), 54 deletions(-) (limited to 'lv2specgen') diff --git a/lv2specgen/lv2specgen.py b/lv2specgen/lv2specgen.py index b356bd7..00310d6 100755 --- a/lv2specgen/lv2specgen.py +++ b/lv2specgen/lv2specgen.py @@ -304,6 +304,22 @@ def getComment(m, urinode, classlist, proplist, instalist): return text markup = rgx.sub(translateLink, markup) + # Transform names like #foo into links into this spec if possible + rgx = re.compile('([ \t\n\r\f\v^]+)\#([a-zA-Z0-9_-]+)') + def translateLocalLink(match): + text = match.group(0) + space = match.group(1) + name = match.group(2) + uri = rdflib.URIRef(spec_ns + name) + if ((classlist and uri in classlist) or + (instalist and uri in instalist) or + (proplist and uri in proplist)): + return '%s%s' % (space, name, name) + else: + print("warning: Link to undefined resource <%s>\n" % name) + return text + markup = rgx.sub(translateLocalLink, markup) + if have_lxml: try: # Parse and validate documentation as XHTML Basic 1.1 @@ -327,6 +343,10 @@ def getComment(m, urinode, classlist, proplist, instalist): os.chdir(oldcwd) except Exception as e: print("Invalid lv2:documentation for %s\n%s" % (urinode, e)) + line_num = 1 + for line in doc.split('\n'): + print('%3d: %s' % (line_num, line)) + line_num += 1 return markup @@ -722,17 +742,12 @@ def getAnchor(uri): return getShortName(uri) -def buildIndex(m, classlist, proplist, instalist=None): - """ - Builds the A-Z list of terms. Args are a list of classes (strings) and - a list of props (strings) - """ - - if len(classlist) == 0 and len(proplist) == 0 and ( - not instalist or len(instalist) == 0): +def buildIndex(m, classlist, proplist, instalist=None, filelist=None): + if not (classlist or proplist or instalist or filelist): return '' - azlist = '
' + head = '' + body = '' def termLink(m, t): if str(t).startswith(spec_ns_str): @@ -742,7 +757,8 @@ def buildIndex(m, classlist, proplist, instalist=None): return '%s' % (str(t), str(t)) if (len(classlist) > 0): - azlist += "
Classes
    " + head += 'Classes' + body += '
      ' classlist.sort() shown = {} for c in classlist: @@ -759,7 +775,7 @@ def buildIndex(m, classlist, proplist, instalist=None): continue shown[c] = True - azlist += '
    • ' + termLink(m, c) + body += '
    • ' + termLink(m, c) def class_tree(c): tree = '' shown[c] = True @@ -776,29 +792,41 @@ def buildIndex(m, classlist, proplist, instalist=None): if tree != '': tree = '
        ' + tree + '
      ' return tree - azlist += class_tree(c) - azlist += '
      • ' - azlist += '
\n' + body += class_tree(c) + body += '' + body += '\n' if (len(proplist) > 0): - azlist += "
Properties
" + head += 'Properties' + body += '
    ' proplist.sort() - props = [] for p in proplist: - props += [termLink(m, p)] - azlist += ', '.join(props) + '
\n' + body += '
  • %s
    • ' % termLink(m, p) + body += '\n' if (instalist != None and len(instalist) > 0): - azlist += "
    Instances
    " - instas = [] + head += 'Instances' + body += '
      ' + instalist.sort() for i in instalist: p = getShortName(i) anchor = getAnchor(i) - instas += ['%s' % (anchor, p)] - azlist += ', '.join(instas) + '
    \n' + body += '
  • %s
    • ' % (anchor, p) + body += '\n' + + if (filelist != None and len(filelist) > 0): + head += 'Files' + body += '\n' - azlist += '\n
    ' - return azlist + head += '' + body += '' + return '%s\n%s
    ' % (head, body) def add(where, key, value): @@ -1049,8 +1077,11 @@ def load_tags(path, docdir): return e.firstChild.nodeValue return '' - def linkTo(sym, url): - return '%s' % (docdir, url, sym) + def linkTo(filename, anchor, sym): + if anchor: + return '%s' % (docdir, filename, anchor, sym) + else: + return '%s' % (docdir, filename, sym) tagdoc = xml.dom.minidom.parse(path) root = tagdoc.documentElement @@ -1062,13 +1093,15 @@ def load_tags(path, docdir): name = getChildText(cn, 'name') filename = getChildText(cn, 'filename') + anchor = getChildText(cn, 'anchor') if not filename.endswith('.html'): filename += '.html' - linkmap[name] = linkTo(name, filename) + if cn.getAttribute('kind') != 'group': + linkmap[name] = linkTo(filename, anchor, name) prefix = '' - if cn.getAttribute('kind') != 'file': + if cn.getAttribute('kind') == 'struct': prefix = name + '::' members = cn.getElementsByTagName('member') @@ -1076,8 +1109,7 @@ def load_tags(path, docdir): mname = prefix + getChildText(m, 'name') mafile = getChildText(m, 'anchorfile') manchor = getChildText(m, 'anchor') - linkmap[mname] = linkTo( - mname, '%s#%s' % (mafile, manchor)) + linkmap[mname] = linkTo(mafile, manchor, mname) return linkmap @@ -1167,7 +1199,21 @@ def specgen(specloc, indir, style_uri, docdir, tags, opts, instances=False): instalist = getInstances(m, classlist, proplist) instalist.sort(lambda x, y: cmp(getShortName(x).lower(), getShortName(y).lower())) - azlist = buildIndex(m, classlist, proplist, instalist) + filelist = [] + see_also_files = specProperties(m, spec, rdfs.seeAlso) + see_also_files.sort() + for f in see_also_files: + uri = str(f) + if uri[:7] == 'file://': + uri = uri[7:] + if uri[:len(abs_bundle_path)] == abs_bundle_path: + uri = uri[len(abs_bundle_path) + 1:] + else: + continue # Skip seeAlso file outside bundle + + filelist += [uri] + + azlist = buildIndex(m, classlist, proplist, instalist, filelist) # Generate Term HTML termlist = docTerms('Property', proplist, m, classlist, proplist, instalist) @@ -1221,28 +1267,8 @@ def specgen(specloc, indir, style_uri, docdir, tags, opts, instances=False): template = template.replace('@VERSION@', version_string) - file_list = '' - see_also_files = specProperties(m, spec, rdfs.seeAlso) - see_also_files.sort() - for f in see_also_files: - uri = str(f) - if uri[:7] == 'file://': - uri = uri[7:] - if uri[:len(abs_bundle_path)] == abs_bundle_path: - uri = uri[len(abs_bundle_path) + 1:] - else: - continue # Skip seeAlso file outside bundle - - entry = '%s' % (uri, uri) - if uri.endswith('.h') or uri.endswith('.hpp'): - name = os.path.basename(uri) - entry += ' (docs) ' % ( - docdir + '/' + name.replace('.', '_8') + '.html') - file_list += '
  • %s
    • ' % entry - elif not uri.endswith('.doap.ttl'): - file_list += '
  • %s
    • ' % entry - - template = template.replace('@FILES@', file_list) + content_links = '
  • API
    • ' % os.path.join(docdir, 'group__%s.html' % basename) + template = template.replace('@CONTENT_LINKS@', content_links) comment = getComment(m, rdflib.URIRef(spec_url), classlist, proplist, instalist) if comment != '': diff --git a/lv2specgen/template.html b/lv2specgen/template.html index f82e7aa..fb79c31 100644 --- a/lv2specgen/template.html +++ b/lv2specgen/template.html @@ -40,7 +40,7 @@
  • Index
  • Reference
  • History
    • - @FILES@ + @CONTENT_LINKS@ -- cgit v1.2.1