doctool: Output formatter for DevDocs

In order to generate HTML output that DevDocs can easily scrape and
display, we add a new output format to g-ir-doc-tool (--format=devdocs).
It works similarly to the Mallard output format, but generates very simple
HTML instead. We add a new set of Mako templates to generate this output.

14 files changed, 173 insertions, 0 deletions

diff --git a/giscanner/doctemplates/devdocs/Gjs/_method.tmpl b/giscanner/doctemplates/devdocs/Gjs/_method.tmpl
new file mode 100644
index 00000000..0374ba40
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_method.tmpl
@@ -0,0 +1,48 @@
+<%def name="describe_parameters(m, static=False, virtual=False)">
+  <dl>
+    % if static:
+      <dt>Type:</dt>
+      <dd>Static</dd>
+    % elif virtual:
+      <dt>Type:</dt>
+      <dd>Virtual</dd>
+    % endif
+    % if m.parameters:
+      <dt>Parameters:</dt>
+      <dd>
+        <ul>
+          % for p in m.parameters:
+            <li>
+              <strong>${p.argname}</strong>
+              (<code>${formatter.format_type(p.type)}</code>)
+              % if p.doc:
+                &mdash; ${formatter.format_inline(m, p.doc)}
+              % endif
+            </li>
+          % endfor
+        </ul>
+      </dd>
+    % endif
+    % if m.retval.type != ast.TYPE_NONE:
+      <dt>Returns:</dt>
+      <dd>
+        (<code>${formatter.format_type(m.retval.type)}</code>)
+        % if m.retval.doc:
+          ${formatter.format_inline(m, m.retval.doc)}
+        % endif
+      </dd>
+    % endif
+  </dl>
+</%def>
+
+<%def name="method(m, static=False, virtual=False)">
+  <% invocation = ", ".join(map(lambda p: p.argname, m.parameters)) %>
+  <h3>
+    <span class="entry ${get_node_kind(m)}" id="${formatter.make_anchor(m)}">
+    ${formatter.format_function_name(m)}<!-- no space
+    --></span><!-- no space
+    -->(${formatter.format_in_parameters(m)})
+  </h3>
+  ${describe_parameters(m, static, virtual)}
+  ${formatter.format(m, m.doc)}
+</%def>
diff --git a/giscanner/doctemplates/devdocs/Gjs/_methods.tmpl b/giscanner/doctemplates/devdocs/Gjs/_methods.tmpl
new file mode 100644
index 00000000..e876cd68
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_methods.tmpl
@@ -0,0 +1,4 @@
+<%namespace name="method" file="_method.tmpl"/>
+% for m in getattr(node, 'methods', []):
+  ${method.method(m)}
+% endfor
diff --git a/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl b/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl
new file mode 100644
index 00000000..ef9913aa
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl
@@ -0,0 +1,34 @@
+<%!
+  def dash_to_underscore(string):
+    return '_'.join(string.split('-'))
+
+  def dash_to_camel(string):
+    words = string.split('-')
+    return ''.join([words[0]] + [word.title() for word in words[1:]])
+%>
+% if getattr(node, 'properties', []):
+  <h2>Property Details</h2>
+  % for p in node.properties:
+    <h3 class="entry property" id="${formatter.make_anchor(p)}">
+      ${p.name | dash_to_underscore}
+    </h3>
+    <dl>
+      % if p.name.lower() != p.name:
+        <dt>Names</dt>
+        <dd>
+          <code>${p.name}</code>, <code>${p.name | dash_to_underscore}</code>,
+          <code>${p.name | dash_to_camel}</code>
+        </dd>
+      % endif
+      <dt>Type</dt>
+      <dd><code>${formatter.format_type(p.type)}</code></dd>
+      ##<dt>Default value</dt>
+      ##<dd>Not currently stored in GIR</dd>
+      <dt>Flags</dt>
+      <dd>${formatter.format_property_flags(p)}</dd>
+    </dl>
+    % if p.doc:
+      ${formatter.format(node, p.doc)}
+    % endif
+  % endfor
+% endif
diff --git a/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl b/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl
new file mode 100644
index 00000000..4065df83
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl
@@ -0,0 +1,20 @@
+<%namespace name="method" file="_method.tmpl"/>
+% if getattr(node, 'signals', []):
+  <h2>Signal Details</h2>
+  % for s in node.signals:
+    <h3>
+      <span class="entry signal" id="${formatter.make_anchor(s)}">
+        ${s.name}<!-- no space
+      --></span><!--
+      -->(${formatter.format_in_parameters(s)})
+    </h3>
+    <dl>
+      <dt>Flags</dt>
+      <dd>${formatter.format_signal_flags(s)}</dd>
+      ${method.describe_parameters(s)}
+    </dl>
+    % if s.doc:
+      ${formatter.format(node, s.doc)}
+    % endif
+  % endfor
+% endif
diff --git a/giscanner/doctemplates/devdocs/Gjs/_staticmethods.tmpl b/giscanner/doctemplates/devdocs/Gjs/_staticmethods.tmpl
new file mode 100644
index 00000000..dcd542e1
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_staticmethods.tmpl
@@ -0,0 +1,4 @@
+<%namespace name="method" file="_method.tmpl"/>
+% for m in getattr(node, 'static_methods', []) + getattr(node, 'constructors', []):
+  ${method.method(m, static=True)}
+% endfor
diff --git a/giscanner/doctemplates/devdocs/Gjs/_vfuncs.tmpl b/giscanner/doctemplates/devdocs/Gjs/_vfuncs.tmpl
new file mode 100644
index 00000000..2966ede4
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_vfuncs.tmpl
@@ -0,0 +1,6 @@
+<%namespace name="method" file="_method.tmpl"/>
+% if getattr(node, 'virtual_methods', []):
+  % for m in node.virtual_methods:
+    ${method.method(m, virtual=True)}
+  % endfor
+% endif
diff --git a/giscanner/doctemplates/devdocs/Gjs/base.tmpl b/giscanner/doctemplates/devdocs/Gjs/base.tmpl
new file mode 100644
index 00000000..95800da8
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/base.tmpl
@@ -0,0 +1,15 @@
+<html>
+<body>
+  <section>
+    <h1 class="${page_kind}">${formatter.format_page_name(node)}</h1>
+    <h2>Details</h2>
+    ${formatter.format(node, node.doc)}
+    <%include file="_staticmethods.tmpl"/>
+    <%include file="_methods.tmpl"/>
+    <%include file="_vfuncs.tmpl"/>
+    <%include file="_signals.tmpl"/>
+    <%include file="_properties.tmpl"/>
+    ${self.body()}
+  </section>
+</body>
+</html>
diff --git a/giscanner/doctemplates/devdocs/Gjs/callback.tmpl b/giscanner/doctemplates/devdocs/Gjs/callback.tmpl
new file mode 100644
index 00000000..2795ee3c
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/callback.tmpl
@@ -0,0 +1,3 @@
+<%namespace name="method" file="_method.tmpl"/>
+<%inherit file="base.tmpl"/>
+${method.describe_parameters(node)}
diff --git a/giscanner/doctemplates/devdocs/Gjs/class.tmpl b/giscanner/doctemplates/devdocs/Gjs/class.tmpl
new file mode 100644
index 00000000..9d2b5238
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/class.tmpl
@@ -0,0 +1 @@
+<%inherit file="base.tmpl"/>
diff --git a/giscanner/doctemplates/devdocs/Gjs/default.tmpl b/giscanner/doctemplates/devdocs/Gjs/default.tmpl
new file mode 100644
index 00000000..5130fadc
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/default.tmpl
@@ -0,0 +1,6 @@
+<%inherit file="base.tmpl"/>
+% if isinstance(node, ast.Constant):
+  <code>
+    const ${formatter.format_page_name(node)} = ${node.value};
+  </code>
+% endif
diff --git a/giscanner/doctemplates/devdocs/Gjs/enum.tmpl b/giscanner/doctemplates/devdocs/Gjs/enum.tmpl
new file mode 100644
index 00000000..a66cbefa
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/enum.tmpl
@@ -0,0 +1,16 @@
+<%inherit file="base.tmpl"/>
+<ul>
+% for m in node.members:
+  <li>
+    <code>
+      <span class="entry" id="${formatter.make_anchor(m)}">
+        ${m.name.upper()}
+      </span>
+      = ${m.value}
+    </code>
+    % if m.doc:
+      &mdash; ${formatter.format_inline(node, m.doc)}
+    % endif
+  </li>
+% endfor
+</ul>
diff --git a/giscanner/doctemplates/devdocs/Gjs/function.tmpl b/giscanner/doctemplates/devdocs/Gjs/function.tmpl
new file mode 100644
index 00000000..9d2b5238
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/function.tmpl
@@ -0,0 +1 @@
+<%inherit file="base.tmpl"/>
diff --git a/giscanner/doctemplates/devdocs/Gjs/interface.tmpl b/giscanner/doctemplates/devdocs/Gjs/interface.tmpl
new file mode 100644
index 00000000..9d2b5238
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/interface.tmpl
@@ -0,0 +1 @@
+<%inherit file="base.tmpl"/>
diff --git a/giscanner/doctemplates/devdocs/Gjs/namespace.tmpl b/giscanner/doctemplates/devdocs/Gjs/namespace.tmpl
new file mode 100644
index 00000000..5a90634a
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/namespace.tmpl
@@ -0,0 +1,14 @@
+<html>
+<body>
+  <section>
+    <h1 class="namespace">${node.name}</h1>
+  </section>
+  <ul>
+  % for n in node.values():
+    % if formatter.should_render_node(n):
+      <li>${formatter.format_inline(n, formatter.format_xref(n))}</li>
+    % endif
+  % endfor
+  </ul>
+</body>
+</html>