docwriter: Option to select output format

For generating other output formats such as DevDocs-ready HTML, we add an
output format option (-f). The default output format is "mallard" which
leaves the existing behaviour unchanged.

We can fold the existing --write-sections-file option into the new output
format option, as a new "sections" format.

Closes #134.

45 files changed, 625 insertions, 0 deletions

diff --git a/giscanner/doctemplates/mallard/C/callback.tmpl b/giscanner/doctemplates/mallard/C/callback.tmpl
new file mode 100644
index 00000000..f285ff68
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/callback.tmpl
@@ -0,0 +1,4 @@
+<%inherit file="./function.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+  </%block>
diff --git a/giscanner/doctemplates/mallard/C/class.tmpl b/giscanner/doctemplates/mallard/C/class.tmpl
new file mode 100644
index 00000000..3f18b021
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/class.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/class.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/constructor.tmpl b/giscanner/doctemplates/mallard/C/constructor.tmpl
new file mode 100644
index 00000000..a03d2825
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/constructor.tmpl
@@ -0,0 +1 @@
+<%inherit file="./function.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/default.tmpl b/giscanner/doctemplates/mallard/C/default.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/default.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/enum.tmpl b/giscanner/doctemplates/mallard/C/enum.tmpl
new file mode 100644
index 00000000..1523e0df
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/enum.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/field.tmpl b/giscanner/doctemplates/mallard/C/field.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/field.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/function.tmpl b/giscanner/doctemplates/mallard/C/function.tmpl
new file mode 100644
index 00000000..3f9e6275
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/function.tmpl
@@ -0,0 +1,60 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <api:function>
+      <api:returns>
+        <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
+      </api:returns>
+      <api:name>${formatter.format_function_name(node)}</api:name>
+% for arg in formatter.get_in_parameters(node):
+% if arg.type.ctype == '<varargs>':
+      <api:varargs/>
+% else:
+      <api:arg>
+        <api:type>${formatter.format_type(arg.type) | x}</api:type>
+        <api:name>${formatter.format_parameter_name(node, arg)}</api:name>
+      </api:arg>
+% endif
+% endfor
+    </api:function>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-csrc">
+${node.retval.type.ctype} ${formatter.format_function_name(node)} (\
+% if not formatter.get_in_parameters(node):
+void\
+% else:
+% for ix, arg in enumerate(formatter.get_in_parameters(node)):
+% if ix != 0:
+${' ' * (len(formatter.format_type(node.retval.type)) + len(formatter.format_function_name(node)) + 3)}\
+% endif
+% if arg.type.ctype == '<varargs>':
+...\
+% else:
+${formatter.format_type(arg.type) | x} ${arg.argname}\
+% endif
+% if ix != len(formatter.get_in_parameters(node)) - 1:
+,
+% endif
+% endfor
+% endif
+);
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.get_in_parameters(node) or node.retval:
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval:
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/mallard/C/interface.tmpl b/giscanner/doctemplates/mallard/C/interface.tmpl
new file mode 100644
index 00000000..3f18b021
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/interface.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/class.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/method.tmpl b/giscanner/doctemplates/mallard/C/method.tmpl
new file mode 100644
index 00000000..a03d2825
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/method.tmpl
@@ -0,0 +1 @@
+<%inherit file="./function.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/namespace.tmpl b/giscanner/doctemplates/mallard/C/namespace.tmpl
new file mode 100644
index 00000000..cb8195da
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/namespace.tmpl
@@ -0,0 +1 @@
+<%inherit file="/namespace.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/property.tmpl b/giscanner/doctemplates/mallard/C/property.tmpl
new file mode 100644
index 00000000..6ec9e8e1
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/property.tmpl
@@ -0,0 +1,5 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
diff --git a/giscanner/doctemplates/mallard/C/record.tmpl b/giscanner/doctemplates/mallard/C/record.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/record.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/C/signal.tmpl b/giscanner/doctemplates/mallard/C/signal.tmpl
new file mode 100644
index 00000000..28c0b740
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/signal.tmpl
@@ -0,0 +1,5 @@
+<%inherit file="./function.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
diff --git a/giscanner/doctemplates/mallard/C/vfunc.tmpl b/giscanner/doctemplates/mallard/C/vfunc.tmpl
new file mode 100644
index 00000000..aa0394f4
--- /dev/null
+++ b/giscanner/doctemplates/mallard/C/vfunc.tmpl
@@ -0,0 +1,4 @@
+<%inherit file="./function.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+</%block>
diff --git a/giscanner/doctemplates/mallard/Gjs/callback.tmpl b/giscanner/doctemplates/mallard/Gjs/callback.tmpl
new file mode 100644
index 00000000..d7b97794
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/callback.tmpl
@@ -0,0 +1,27 @@
+<%inherit file="/base.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+function on${node.name}(\
+${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\
+): ${formatter.format_out_parameters(node)} {
+}
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.has_any_parameters(node):
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% for arg in formatter.get_out_parameters(node):
+<item>
+<title><code>${(arg.argname + ' (out)') if arg.direction == 'inout' else arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+</terms>
+% endif
+</%block>
+
diff --git a/giscanner/doctemplates/mallard/Gjs/class.tmpl b/giscanner/doctemplates/mallard/Gjs/class.tmpl
new file mode 100644
index 00000000..7694d726
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/class.tmpl
@@ -0,0 +1,30 @@
+<%inherit file="/class.tmpl"/>
+<%block name="synopsis">
+  <synopsis>\
+% if node.namespace is not None:
+<code>
+const ${namespace.name} = imports.gi.${namespace.name};
+
+let ${formatter.to_lower_camel_case(node.name)} = new ${namespace.name}.${node.name}(\
+% if isinstance(node, (ast.Class, ast.Interface)):
+% if len(node.properties) > 0:
+{
+% for ix, property_ in enumerate(node.properties):
+% if (property_.construct or property_.construct_only) and property_.writable:
+    <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>: value,
+% endif
+% endfor
+}\
+% endif
+% else:
+${formatter.format_gboxed_constructor(node)}\
+% endif
+);
+  </code>\
+% else:
+  <p>
+    This structure is inside ${node.parent.namespace.name}.${node.parent.name}
+    and can only be used as a field of that.
+  </p>
+% endif
+</synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Gjs/constructor.tmpl b/giscanner/doctemplates/mallard/Gjs/constructor.tmpl
new file mode 100644
index 00000000..a03d2825
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/constructor.tmpl
@@ -0,0 +1 @@
+<%inherit file="./function.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Gjs/default.tmpl b/giscanner/doctemplates/mallard/Gjs/default.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/default.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Gjs/enum.tmpl b/giscanner/doctemplates/mallard/Gjs/enum.tmpl
new file mode 100644
index 00000000..e239de18
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/enum.tmpl
@@ -0,0 +1,21 @@
+<%! page_type="guide" %>
+<%inherit file="/base.tmpl"/>
+<%block name="details">
+% if node.members:
+<terms>
+% for member in node.members:
+<item>
+<title><code>${node.name}.${member.name.upper()}</code></title>
+${formatter.format(node, member.doc)}
+</item>
+% endfor
+</terms>
+% endif
+</%block>
+<%block name="links">\
+  <links type="topic" ui:expanded="true"
+         api:type="function" api:mime="${formatter.mime_type}"
+         groups="function" style="linklist">
+    <title>Functions</title>
+  </links>\
+</%block>
\ No newline at end of file
diff --git a/giscanner/doctemplates/mallard/Gjs/field.tmpl b/giscanner/doctemplates/mallard/Gjs/field.tmpl
new file mode 100644
index 00000000..dda82469
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/field.tmpl
@@ -0,0 +1,9 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+${node.parent.name}.${formatter.to_underscores(node)}: ${formatter.format_type(node.type, True)} (${formatter.format_property_flags(node)})
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Gjs/function.tmpl b/giscanner/doctemplates/mallard/Gjs/function.tmpl
new file mode 100644
index 00000000..8e9d7417
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/function.tmpl
@@ -0,0 +1,47 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <api:function>
+      <api:returns>
+        <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
+      </api:returns>
+      <api:name>${node.symbol}</api:name>
+% for arg in formatter.get_in_parameters(node):
+% if arg.type.ctype == '<varargs>':
+      <api:varargs/>
+% else:
+      <api:arg>
+        <api:type>${formatter.format_type(arg.type) | x}</api:type>
+        <api:name>${formatter.format_parameter_name(node, arg)}</api:name>
+      </api:arg>
+% endif
+% endfor
+    </api:function>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+function \
+${node.name if node.shadows is None else node.shadows}(\
+${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\
+): ${formatter.format_out_parameters(node)} {
+    // Gjs wrapper for ${node.symbol}()
+}
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.has_any_parameters(node):
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% for arg in formatter.get_out_parameters(node):
+<item>
+<title><code>${(arg.argname + ' (out)') if arg.direction == 'inout' else arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/mallard/Gjs/interface.tmpl b/giscanner/doctemplates/mallard/Gjs/interface.tmpl
new file mode 100644
index 00000000..2f01f20f
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/interface.tmpl
@@ -0,0 +1,17 @@
+<%inherit file="/class.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code>
+const ${namespace.name} = imports.gi.${namespace.name};
+
+let ${formatter.to_underscores(node).lower()} = new ${namespace.name}.${node.name}(\
+% if len(node.properties) > 0:
+{
+% for ix, property_ in enumerate(node.properties):
+% if (property_.construct or property_.construct_only) and property_.writable:
+    <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>: value,
+% endif
+% endfor
+}\
+% endif
+);
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Gjs/method.tmpl b/giscanner/doctemplates/mallard/Gjs/method.tmpl
new file mode 100644
index 00000000..a03d2825
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/method.tmpl
@@ -0,0 +1 @@
+<%inherit file="./function.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Gjs/namespace.tmpl b/giscanner/doctemplates/mallard/Gjs/namespace.tmpl
new file mode 100644
index 00000000..4d80c2a5
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/namespace.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/namespace.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Gjs/property.tmpl b/giscanner/doctemplates/mallard/Gjs/property.tmpl
new file mode 100644
index 00000000..dda82469
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/property.tmpl
@@ -0,0 +1,9 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+${node.parent.name}.${formatter.to_underscores(node)}: ${formatter.format_type(node.type, True)} (${formatter.format_property_flags(node)})
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Gjs/record.tmpl b/giscanner/doctemplates/mallard/Gjs/record.tmpl
new file mode 100644
index 00000000..1523e0df
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/record.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Gjs/signal.tmpl b/giscanner/doctemplates/mallard/Gjs/signal.tmpl
new file mode 100644
index 00000000..7c508162
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/signal.tmpl
@@ -0,0 +1,38 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+connect('${node.name}', function (${formatter.to_lower_camel_case(node.parent.name)}, \
+% for arg in formatter.get_in_parameters(node):
+% if arg.type.target_fundamental != 'none':
+${arg.argname}: ${formatter.format_type(arg.type, True)}, \
+% endif
+% endfor
+): ${formatter.format_type(node.retval.type, True)});
+  </code></synopsis></%block>
+<%block name="details">
+<terms>
+<item>
+<title><code>${formatter.to_lower_camel_case(node.parent.name)}</code></title>
+<p>instance of ${formatter.format_xref(node.parent)} that is emitting the signal</p>
+</item>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval and \
+     node.retval.type.ctype != 'void' and \
+     node.retval.type.ctype is not None:
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+</%block>
+
diff --git a/giscanner/doctemplates/mallard/Gjs/vfunc.tmpl b/giscanner/doctemplates/mallard/Gjs/vfunc.tmpl
new file mode 100644
index 00000000..2bd1127d
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Gjs/vfunc.tmpl
@@ -0,0 +1,27 @@
+<%inherit file="/base.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+function vfunc_${node.name}(\
+${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\
+): ${formatter.format_out_parameters(node)} {
+}
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.get_in_parameters(node) or node.retval:
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+% endif
+</%block>
+
diff --git a/giscanner/doctemplates/mallard/Python/callback.tmpl b/giscanner/doctemplates/mallard/Python/callback.tmpl
new file mode 100644
index 00000000..4fcbfe3b
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/callback.tmpl
@@ -0,0 +1,27 @@
+<%inherit file="/base.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-python">
+% if formatter.get_in_parameters(node):
+@accepts(${', '.join((formatter.format_type(arg.type) for arg in formatter.get_in_parameters(node)))})
+% endif
+@returns(${formatter.format_type(node.retval.type) | x})
+def on_${node.name}(${', '.join((arg.argname for arg in formatter.get_in_parameters(node)))}):
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.get_in_parameters(node) or node.retval:
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/mallard/Python/class.tmpl b/giscanner/doctemplates/mallard/Python/class.tmpl
new file mode 100644
index 00000000..51d25a91
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/class.tmpl
@@ -0,0 +1,18 @@
+<%inherit file="/class.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code>
+from gi.repository import ${namespace.name}
+
+${formatter.to_underscores(node).lower()} = ${namespace.name}.${node.name}(\
+% if isinstance(node, (ast.Class, ast.Interface)):
+% for ix, property_ in enumerate(node.properties):
+% if property_.construct or property_.construct_only or property_.writable:
+<link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>=value\
+% if ix != len(node.properties) - 1:
+, \
+% endif
+% endif
+% endfor
+% endif
+)
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Python/constructor.tmpl b/giscanner/doctemplates/mallard/Python/constructor.tmpl
new file mode 100644
index 00000000..a03d2825
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/constructor.tmpl
@@ -0,0 +1 @@
+<%inherit file="./function.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Python/default.tmpl b/giscanner/doctemplates/mallard/Python/default.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/default.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Python/enum.tmpl b/giscanner/doctemplates/mallard/Python/enum.tmpl
new file mode 100644
index 00000000..35cdd439
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/enum.tmpl
@@ -0,0 +1,13 @@
+<%inherit file="/base.tmpl"/>
+<%block name="details">
+% if node.members:
+<terms>
+% for member in node.members:
+<item>
+<title><code>${node.name}.${member.name.upper()}</code></title>
+${formatter.format(node, member.doc)}
+</item>
+% endfor
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/mallard/Python/field.tmpl b/giscanner/doctemplates/mallard/Python/field.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/field.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Python/function.tmpl b/giscanner/doctemplates/mallard/Python/function.tmpl
new file mode 100644
index 00000000..7ad1ac04
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/function.tmpl
@@ -0,0 +1,47 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <api:function>
+      <api:returns>
+        <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
+      </api:returns>
+      <api:name>${node.symbol}</api:name>
+% for arg in formatter.get_in_parameters(node):
+% if arg.type.ctype == '<varargs>':
+      <api:varargs/>
+% else:
+      <api:arg>
+        <api:type>${formatter.format_type(arg.type) | x}</api:type>
+        <api:name>${formatter.format_parameter_name(node, arg)}</api:name>
+      </api:arg>
+% endif
+% endfor
+    </api:function>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-python">
+% if formatter.get_in_parameters(node):
+@accepts(${', '.join((formatter.format_type(arg.type) for arg in formatter.get_in_parameters(node)))})
+% endif
+@returns(${formatter.format_type(node.retval.type) | x})
+def ${node.name}(${', '.join((formatter.format_parameter_name(node, arg) for arg in formatter.get_in_parameters(node)))}):
+    # Python wrapper for ${node.symbol}()
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.get_in_parameters(node) or node.retval:
+<terms>
+% for ix, arg in enumerate(formatter.get_in_parameters(node)):
+<item>
+<title><code>${formatter.format_parameter_name(node, arg)}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<item>
+<title><code>Returns</code></title>
+{formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/mallard/Python/interface.tmpl b/giscanner/doctemplates/mallard/Python/interface.tmpl
new file mode 100644
index 00000000..b3596a8d
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/interface.tmpl
@@ -0,0 +1,16 @@
+<%inherit file="/class.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code>
+from gi.repository import ${namespace.name}
+
+${formatter.to_underscores(node).lower()} = ${namespace.name}.${node.name}(\
+% for ix, property_ in enumerate(node.properties):
+% if property_.construct or property_.construct_only or property_.writable:
+<link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>=value\
+% if ix != len(node.properties) - 1:
+, \
+% endif
+% endif
+% endfor
+)\
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Python/method.tmpl b/giscanner/doctemplates/mallard/Python/method.tmpl
new file mode 100644
index 00000000..a03d2825
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/method.tmpl
@@ -0,0 +1 @@
+<%inherit file="./function.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Python/namespace.tmpl b/giscanner/doctemplates/mallard/Python/namespace.tmpl
new file mode 100644
index 00000000..4d80c2a5
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/namespace.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/namespace.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Python/property.tmpl b/giscanner/doctemplates/mallard/Python/property.tmpl
new file mode 100644
index 00000000..c93d59b7
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/property.tmpl
@@ -0,0 +1,9 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-python">
+"${node.name}"             ${formatter.format_type(node.type)}                : ${formatter.format_property_flags(node)}
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/mallard/Python/record.tmpl b/giscanner/doctemplates/mallard/Python/record.tmpl
new file mode 100644
index 00000000..1523e0df
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/record.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/mallard/Python/signal.tmpl b/giscanner/doctemplates/mallard/Python/signal.tmpl
new file mode 100644
index 00000000..c61b7229
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/signal.tmpl
@@ -0,0 +1,41 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-python">
+def callback(${formatter.to_underscores(node.parent).lower()}, \
+% for arg in formatter.get_in_parameters(node):
+${arg.argname}, \
+% endfor
+user_param1, ...)
+  </code></synopsis></%block>
+<%block name="details">
+<terms>
+<item>
+<title><code>${formatter.to_underscores(node.parent).lower()}</code></title>
+<p>instance of ${formatter.format_xref(node.parent)} that is emitting the signal</p>
+</item>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+<title><code>user_param1</code></title>
+<p>first user parameter (if any) specified with the connect() method</p>
+<item>
+<title><code>...</code></title>
+<p>additional user parameters (if any)</p>
+</item>
+% if node.retval and \
+     node.retval.type.ctype != 'void' and \
+     node.retval.type.ctype is not None:
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+</%block>
diff --git a/giscanner/doctemplates/mallard/Python/vfunc.tmpl b/giscanner/doctemplates/mallard/Python/vfunc.tmpl
new file mode 100644
index 00000000..2c532e70
--- /dev/null
+++ b/giscanner/doctemplates/mallard/Python/vfunc.tmpl
@@ -0,0 +1,27 @@
+<%inherit file="/base.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-python">
+% if formatter.get_in_parameters(node):
+@accepts(${', '.join((formatter.format_type(arg.type) for arg in formatter.get_in_parameters(node)))})
+% endif
+@returns(${formatter.format_type(node.retval.type) | x})
+def do_${node.name}(${', '.join((arg.argname for arg in formatter.get_in_parameters(node)))}):
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.get_in_parameters(node) or node.retval:
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/mallard/base.tmpl b/giscanner/doctemplates/mallard/base.tmpl
new file mode 100644
index 00000000..7a1d8db2
--- /dev/null
+++ b/giscanner/doctemplates/mallard/base.tmpl
@@ -0,0 +1,20 @@
+<%! page_type="topic" %>\
+<?xml version="1.0"?>
+<page id="${page_id}"
+      type="${self.attr.page_type}"
+      style="${page_kind}"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info><%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+</%block>\
+  </info>
+  <title><%block name="title">${formatter.format_page_name(node)}</%block></title><%block name="synopsis"></%block><%block name="doc">
+${formatter.format(node, node.doc)}
+</%block><%block name="since_version">\
+% if node.version:
+  <p>Since ${node.version}</p>\
+% endif
+</%block><%block name="details"></%block><%block name="links"></%block>
+</page>
diff --git a/giscanner/doctemplates/mallard/class.tmpl b/giscanner/doctemplates/mallard/class.tmpl
new file mode 100644
index 00000000..86333866
--- /dev/null
+++ b/giscanner/doctemplates/mallard/class.tmpl
@@ -0,0 +1,61 @@
+<%! page_type="guide" %>\
+<%inherit file="/base.tmpl"/>
+<%block name="details">
+% if isinstance(node, ast.Class):
+  <synopsis>
+    <title>Hierarchy</title>
+    <tree>
+% for class_ in formatter.get_class_hierarchy(node):
+      <item>
+        <code>${class_.namespace.name}.${class_.name}</code>
+% endfor
+% for class_ in formatter.get_class_hierarchy(node):
+      </item>
+% endfor
+    </tree>
+  </synopsis>
+% elif isinstance(node, ast.Interface):
+  <synopsis>
+    <title>Prerequisites</title>
+    <p>${node.name} requires ${formatter.format_prerequisites(node)}</p>
+  </synopsis>
+  <synopsis>
+    <title>Known Implementations</title>
+    <p>${formatter.format_known_implementations(node)}</p>
+  </synopsis>
+% endif
+</%block>
+<%block name="links">\
+  <links type="topic" ui:expanded="true"
+         api:type="function" api:mime="${formatter.mime_type}"
+         groups="constructor" style="linklist">
+    <title>Constructors</title>
+  </links>
+  <links type="topic" ui:expanded="true"
+         api:type="function" api:mime="${formatter.mime_type}"
+         groups="method" style="linklist">
+    <title>Methods</title>
+  </links>
+  <links type="topic" ui:expanded="true"
+         api:type="function" api:mime="${formatter.mime_type}"
+         groups="function" style="linklist">
+    <title>Static Functions</title>
+  </links>
+% if isinstance(node, (ast.Class, ast.Interface)):
+  <links type="topic" ui:expanded="true" groups="property" style="linklist">
+    <title>Properties</title>
+  </links>
+  <links type="topic" ui:expanded="true" groups="signal" style="linklist">
+    <title>Signals</title>
+  </links>
+  <links type="topic" ui:expanded="true" groups="vfunc" style="linklist">
+    <title>Virtual functions</title>
+  </links>
+% endif
+  <links type="topic" ui:expanded="true" groups="field" style="linklist">
+    <title>Fields</title>
+  </links>
+  <links type="topic" ui:expanded="true" groups="#first #default #last" style="linklist">
+    <title>Other</title>
+  </links>\
+</%block>
diff --git a/giscanner/doctemplates/mallard/namespace.tmpl b/giscanner/doctemplates/mallard/namespace.tmpl
new file mode 100644
index 00000000..d4edcec0
--- /dev/null
+++ b/giscanner/doctemplates/mallard/namespace.tmpl
@@ -0,0 +1,16 @@
+<%! page_type="guide" %>\
+<%inherit file="/base.tmpl"/>
+<%block name="doc"></%block>
+<%block name="info"></%block>
+<%block name="links">
+  <links type="topic" ui:expanded="true" groups="class interface" style="linklist">
+    <title>Classes</title>
+  </links>
+  <links type="topic" ui:expanded="true" groups="function" style="linklist">
+    <title>Functions</title>
+  </links>
+  <links type="topic" ui:expanded="true" groups="#first #default #last" style="linklist">
+    <title>Other</title>
+  </links>
+</%block>
+<%block name="since_version"></%block>