aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2019-04-27 15:09:18 +0200
committerDavid Robillard <d@drobilla.net>2019-04-27 17:20:53 +0200
commitbfcdcde2b9a5c20688fe73a841c288218acd975d (patch)
treea9468bceb2adfb9bb2af13a08a512e84c5cbc61e
parent0d5b9864429edf34575b066b4a2d8988b8b8e302 (diff)
downloadlv2-bfcdcde2b9a5c20688fe73a841c288218acd975d.tar.xz
Flatten documentation to fix fragment links
This removes all the extra bundle content from the documentation output and instead makes pages directly at the URI of specifications. This way, links to fragments in spec pages (which are often copy and pasted) are correct fragment identifiers like <http://lv2plug.in/ns/lv2core#Plugin> instead of <http://lv2plug.in/ns/lv2core/#Plugin>.
-rw-r--r--doc/htaccess.in6
-rw-r--r--lv2/buf-size/buf-size.ttl2
-rw-r--r--lv2/midi/midi.ttl4
-rw-r--r--lv2/patch/patch.ttl4
-rw-r--r--lv2/state/state.ttl14
-rw-r--r--lv2/uri-map/uri-map.ttl2
-rw-r--r--lv2/urid/urid.ttl2
-rwxr-xr-xlv2specgen/lv2specgen.py13
-rw-r--r--wscript65
9 files changed, 52 insertions, 60 deletions
diff --git a/doc/htaccess.in b/doc/htaccess.in
index 7a21951..e1ac1df 100644
--- a/doc/htaccess.in
+++ b/doc/htaccess.in
@@ -13,12 +13,12 @@ RewriteCond %{HTTP_ACCEPT} !application/rdf\+xml.*(text/html|application/xhtml\+
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml\+xml [OR]
RewriteCond %{HTTP_USER_AGENT} ^Mozilla/.*
-RewriteRule ^$ @NAME@.html [L]
+RewriteRule ^(.*)$ $1.html [L]
# Rewrite rule to serve Turtle content from the vocabulary URI if requested
RewriteCond %{HTTP_ACCEPT} text/turtle [OR]
RewriteCond %{HTTP_ACCEPT} application/x-turtle
-RewriteRule ^$ @NAME@.ttl [L]
+RewriteRule ^(.*)$ $1.ttl [L]
# Serve HTML page by default
-RewriteRule ^$ @NAME@.html [L]
+RewriteRule ^(.*)$ $1.html [L]
diff --git a/lv2/buf-size/buf-size.ttl b/lv2/buf-size/buf-size.ttl
index f8a9d60..3464284 100644
--- a/lv2/buf-size/buf-size.ttl
+++ b/lv2/buf-size/buf-size.ttl
@@ -18,7 +18,7 @@ the block length.</p>
<p>This extension defines features and properties but has no special purpose
API of its own. The host provides all the relevant information to the plugin
-as <a href="../options/options.html#options">options</a>.</p>
+as <a href="options.html#options">options</a>.</p>
<p>To require restrictions on the block length, plugins can require additional
features: bufsz:boundedBlockLength, bufsz:powerOf2BlockLength, and
diff --git a/lv2/midi/midi.ttl b/lv2/midi/midi.ttl
index 23e41b3..571ff7a 100644
--- a/lv2/midi/midi.ttl
+++ b/lv2/midi/midi.ttl
@@ -20,8 +20,8 @@ controlling digital music devices.</p>
<p>For plugins that process MIDI (or other situations where MIDI is sent via a
generic transport) the main type defined here, midi:MidiEvent, can be mapped to
an integer and used as the type of an LV2 <a
-href="../atom/atom.html#Atom">Atom</a> or <a
-href="../event/event.html#Event">Event</a>.</p>
+href="atom.html#Atom">Atom</a> or <a
+href="event.html#Event">Event</a>.</p>
<p>This specification also defines a complete human and machine readable
description of the MIDI standard (except for standard controller numbers).
diff --git a/lv2/patch/patch.ttl b/lv2/patch/patch.ttl
index 71c51a3..87432fe 100644
--- a/lv2/patch/patch.ttl
+++ b/lv2/patch/patch.ttl
@@ -18,7 +18,7 @@ plugins, but is useful in many contexts.</p>
<p>The main feature of this design is that the messages themselves are
described in the same format as the data they work with. In particular,
messages can be serialised as a binary <a
-href="../atom/atom.html#Object">Object</a> or in Turtle (or any other RDF
+href="atom.html#Object">Object</a> or in Turtle (or any other RDF
serialisation).</p>
<p>The idea behind using a property-based interface for control is to prevent
@@ -37,7 +37,7 @@ One benefit of this approach is that a persistent state model is available
<p>This specification is strictly metadata and does not define any binary
mechanism, though it can be completely expressed by standard types in the <a
-href="../atom/atom.html">LV2 Atom</a> extension. Thus, hosts can be expected
+href="atom.html">LV2 Atom</a> extension. Thus, hosts can be expected
to be capable of transmitting it between plugins, or between a plugin and its
UI, making it a good choice for advanced plugin control.</p>
""" .
diff --git a/lv2/state/state.ttl b/lv2/state/state.ttl
index c86fea7..9c49195 100644
--- a/lv2/state/state.ttl
+++ b/lv2/state/state.ttl
@@ -44,9 +44,9 @@ single property. The host is free to implement property storage and retrieval
in any way.</p>
<p>Since value types are defined by URI, any type is possible. However, a set
-of standard types is defined by the <a href="../atom/atom.html">LV2 Atom</a>
+of standard types is defined by the <a href="atom.html">LV2 Atom</a>
extension. Use of these types is recommended. Hosts MUST implement at least
-<a href="../atom/atom.html#String">atom:String</a>, which is simply a C
+<a href="atom.html#String">atom:String</a>, which is simply a C
string.</p>
<h3>Referring to Files</h3>
@@ -55,7 +55,7 @@ string.</p>
state. This is done by storing the file's path as a property just like any
other value. However, there are some rules which MUST be followed when storing
paths, see state:mapPath for details. Plugins MUST use the type <a
-href="../atom/atom.html#Path">atom:Path</a> for all paths in their state.</p>
+href="atom.html#Path">atom:Path</a> for all paths in their state.</p>
<p>Plugins are strongly encouraged to avoid creating files, instead storing all
state as properties. However, occasionally the ability to create files is
@@ -204,9 +204,9 @@ plugins.</p>
<q>Don't stop; set playing to false</q>.</p>
<p>This extension does not define a dynamic mechanism for state access and
-manipulation. The <a href="../patch/patch.html">LV2 Patch</a> extension
+manipulation. The <a href="patch.html">LV2 Patch</a> extension
defines a generic set of messages which can be used to access or manipulate
-properties, and the <a href="../atom/atom.html">LV2 Atom</a> extension defines
+properties, and the <a href="atom.html">LV2 Atom</a> extension defines
a port type and data container capable of transmitting those messages.</p>
""" .
@@ -355,7 +355,7 @@ state:threadSafeRestore
is thread-safe and may be called concurrently with audio class functions.</p>
<p>To support this feature, the host MUST pass a <a
-href="../worker/worker.html#schedule">work:schedule</a> feature to the restore
+href="worker.html#schedule">work:schedule</a> feature to the restore
method, which will be used to complete the state restoration. The usual
mechanics of the worker apply: the host will call the plugin's work method,
which emits a response which is later applied in the audio thread.</p>
@@ -372,7 +372,7 @@ state:Changed
way that the host can not otherwise know about.</p>
<p>This is a one-way notification, intended to be used as the type of an <a
-href="../atom/atom.html#Object">Object</a> sent from plugins when
+href="atom.html#Object">Object</a> sent from plugins when
necessary.</p>
<p>Plugins SHOULD emit such an event whenever a change has occurred that would
diff --git a/lv2/uri-map/uri-map.ttl b/lv2/uri-map/uri-map.ttl
index 7f6b0e7..d9f7f5a 100644
--- a/lv2/uri-map/uri-map.ttl
+++ b/lv2/uri-map/uri-map.ttl
@@ -11,7 +11,7 @@
<lv2-uri-map.doap.ttl> ;
lv2:documentation """
<p><span class="warning">This extension is deprecated.</span> New
-implementations should use <a href="../urid/urid.html">LV2 URID</a>
+implementations should use <a href="urid.html">LV2 URID</a>
instead.</p>
<p>This extension defines a simple mechanism for plugins to map URIs to
diff --git a/lv2/urid/urid.ttl b/lv2/urid/urid.ttl
index 29b196a..836d525 100644
--- a/lv2/urid/urid.ttl
+++ b/lv2/urid/urid.ttl
@@ -15,7 +15,7 @@ thread without doing any string comparison. This allows for the extensibility
of RDF but with the performance of integers.</p>
<p>This extension is intended as an improved and simplified replacement for the
-<a href="../uri-map/uri-map.html">uri-map</a> extension, since the <q>map</q>
+<a href="uri-map.html">uri-map</a> extension, since the <q>map</q>
context parameter has been found problematic. This extension is functionally
equivalent to the uri-map extension with a NULL context. New implementations
are encouraged to use this extension for URI mapping.</p>
diff --git a/lv2specgen/lv2specgen.py b/lv2specgen/lv2specgen.py
index 2f2a7d8..ce05c74 100755
--- a/lv2specgen/lv2specgen.py
+++ b/lv2specgen/lv2specgen.py
@@ -1142,15 +1142,13 @@ def writeIndex(model, specloc, index_path, root_path, root_uri):
# Find relative link target
if root_uri and ext_node.startswith(root_uri):
- target = ext_node[len(root_uri):]
+ target = ext_node[len(root_uri):] + '.html'
else:
- target = os.path.relpath(ext_node, root_path)
+ target = os.path.relpath(ext_node, root_path) + '.html'
stem = os.path.splitext(os.path.basename(target))[0]
# Specification (comment is to act as a sort key)
- if not options.online_docs:
- target += '/' + stem + '.html'
row = '<tr><!-- %s --><td><a rel="rdfs:seeAlso" href="%s">%s</a></td>' % (
b, target, name)
@@ -1182,7 +1180,6 @@ def writeIndex(model, specloc, index_path, root_path, root_uri):
row += '</tr>'
- # index = open(os.path.join(out, 'index_rows', b), 'w')
index = open(index_path, 'w')
index.write(row)
index.close()
@@ -1453,8 +1450,6 @@ if __name__ == "__main__":
help='Document instances')
opt.add_option('--copy-style', action='store_true', dest='copy_style',
help='Copy style from template directory to output directory')
- opt.add_option('--online', action='store_true', dest='online_docs',
- help='Generate online documentation')
(options, args) = opt.parse_args()
opts = vars(options)
@@ -1485,9 +1480,7 @@ if __name__ == "__main__":
# Root link
root_path = opts['root_path']
root_uri = opts['root_uri']
- root_link = root_path
- if not options.online_docs:
- root_link = os.path.join(root_path, 'index.html')
+ root_link = os.path.join(root_path, 'index.html')
# Generate spec documentation
specdoc = specgen(
diff --git a/wscript b/wscript
index 2a5aec3..b440b17 100644
--- a/wscript
+++ b/wscript
@@ -306,32 +306,30 @@ def build(bld):
bld.install_files('${LV2DIR}/schemas.lv2/',
bld.path.ant_glob('schemas.lv2/*.ttl'))
+ if bld.env.ONLINE_DOCS:
+ # Generate .htaccess files
+ for d in ('ns', 'ns/ext', 'ns/extensions'):
+ path = os.path.join(str(bld.path.get_bld()), d)
+ bld(features = 'subst',
+ source = 'doc/htaccess.in',
+ target = os.path.join(path, '.htaccess'),
+ install_path = None,
+ BASE = '/' + d)
+
if bld.env.DOCS or bld.env.ONLINE_DOCS:
- # Prepare spec output directories
+ # Copy spec files to build dir
for spec in specs:
- # Copy spec files to build dir
srcpath = spec.srcpath()
basename = os.path.basename(srcpath)
full_path = spec_map[basename]
name = 'lv2core' if basename == 'core' else basename
path = chop_lv2_prefix(full_path)
- base = full_path[len('lv2/lv2plug.in'):]
- for f in bld.path.ant_glob(srcpath + '/*.*'):
- target = os.path.join(path, os.path.basename(f.srcpath()))
- bld(features = 'subst',
- is_copy = True,
- name = 'copy',
- source = f,
- target = target)
-
- # Generate .htaccess file
- if bld.env.ONLINE_DOCS:
- bld(features = 'subst',
- source = 'doc/htaccess.in',
- target = os.path.join(path, '.htaccess'),
- install_path = None,
- NAME = name,
- BASE = base)
+ spec_path = os.path.join(path[3:], name + '.ttl')
+
+ bld(features = 'subst',
+ is_copy = True,
+ source = os.path.join(spec.srcpath(), name + '.ttl'),
+ target = path + '.ttl')
# Copy stylesheets to build directory
for i in ['style.css', 'pygments.css']:
@@ -355,30 +353,32 @@ def build(bld):
ttl_name = name + '.ttl'
index_file = bld.path.get_bld().make_node('index_rows/' + name)
index_files += [index_file.path_from(bld.path)]
- root_path = os.path.relpath('lv2/lv2plug.in/ns', full_path)
- html_path = '%s/%s.html' % (chop_lv2_prefix(full_path), name)
- out_bundle = os.path.dirname(html_path)
+ chopped_path = chop_lv2_prefix(full_path)
+
+ assert chopped_path.startswith('ns/')
+ root_path = os.path.relpath('/', os.path.dirname(chopped_path[2:]))
+ html_path = '%s.html' % chopped_path
+ out_dir = os.path.dirname(html_path)
cmd = (str(bld.path.find_node('lv2specgen/lv2specgen.py')) +
' --root-uri=http://lv2plug.in/ns/ --root-path=' + root_path +
' --list-email=devel@lists.lv2plug.in'
' --list-page=http://lists.lv2plug.in/listinfo.cgi/devel-lv2plug.in'
- ' --style-uri=' + os.path.relpath('aux/style.css', out_bundle) +
- ' --docdir=' + os.path.relpath('doc/html', os.path.dirname(html_path)) +
+ ' --style-uri=' + os.path.relpath('aux/style.css', out_dir) +
+ ' --docdir=' + os.path.relpath('doc/html', out_dir) +
' --tags=%s' % bld.path.get_bld().make_node('doc/tags') +
' --index=' + str(index_file) +
- (' --online' if bld.env.ONLINE_DOCS else '') +
' ${SRC} ${TGT}')
bld(rule = cmd,
source = os.path.join(srcpath, ttl_name),
- target = [html_path, index_file])
+ target = [html_path, index_file],
+ shell = False)
# Install documentation
- if not bld.env.ONLINE_DOCS:
- base = chop_lv2_prefix(srcpath)
- bld.install_files(os.path.join('${DOCDIR}', 'lv2', os.path.dirname(html_path)),
- html_path)
+ base = chop_lv2_prefix(srcpath)
+ bld.install_files(os.path.join('${DOCDIR}', 'lv2', os.path.dirname(html_path)),
+ html_path)
index_files.sort()
bld.add_group()
@@ -390,9 +390,8 @@ def build(bld):
target = 'ns/index.html')
# Install main documentation files
- if not bld.env.ONLINE_DOCS:
- bld.install_files('${DOCDIR}/lv2/aux/', 'aux/style.css')
- bld.install_files('${DOCDIR}/lv2/ns/', 'ns/index.html')
+ bld.install_files('${DOCDIR}/lv2/aux/', 'aux/style.css')
+ bld.install_files('${DOCDIR}/lv2/ns/', 'ns/index.html')
def check_links(ctx):
import subprocess