From 44dea29977be349304a905e01b3ec89f7bdc6168 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Thu, 31 Jan 2013 18:44:09 -0500
Subject: doctool: Rename templates to exclude mallard/the language

As templates are in their own directory and segregated into language
already, this is sort of repeating the issue. At the same time, always
explicitly use relative ("./") or absolute ("/") lookups for templates.

We want to eventually have base templates to share between languages, so
to do so without namespace clashes makes sense.
---
 giscanner/doctemplates/Python/function.tmpl | 62 +++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 giscanner/doctemplates/Python/function.tmpl

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
new file mode 100644
index 00000000..467cfcbe
--- /dev/null
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -0,0 +1,62 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+% if node.parent is not None:
+    <link type="guide" xref="${namespace.name}.${node.parent.name}" group="${page_style}"/>
+% else:
+    <link type="guide" xref="index" group="${page_style}"/>
+% endif
+    <api:function>
+      <api:returns>
+        <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
+      </api:returns>
+      <api:name>${node.symbol}</api:name>
+% if node.is_method:
+      <api:arg>
+        <api:type>${node.parent.ctype} *</api:type>
+        <api:name>self</api:name>
+      </api:arg>
+% endif
+% for arg in node.parameters:
+% if arg.type.ctype == '<varargs>':
+      <api:varargs/>
+% else:
+      <api:arg>
+        <api:type>${formatter.format_type(arg.type) | x}</api:type>
+        <api:name>${arg.argname}</api:name>
+      </api:arg>
+% endif
+% endfor
+    </api:function>
+</%block>
+<%block name="synopsis">
+<synopsis><code mime="text/x-python">
+% if len(node.parameters) != 0:
+@accepts(\
+${', '.join((formatter.format_type(arg.type) for arg in node.parameters))}\
+)
+% endif
+@returns(${formatter.format_type(node.retval.type) | x})
+def \
+${node.name}(\
+% if node.is_method:
+self, \
+% endif
+${', '.join((arg.argname for arg in node.parameters))}\
+):
+    # Python wrapper for ${node.symbol}()
+</code></synopsis>
+</%block>
+<%block name="details">
+% if node.parameters or node.retval:
+<dl>
+% for arg, ix in zip(node.parameters, range(len(node.parameters))):
+<dt><p>${arg.argname} :</p></dt>
+<dd>${formatter.format(node, arg.doc)}</dd>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<dt><p>Returns :</p></dt>
+<dd>${formatter.format(node, node.retval.doc)}</dd>
+% endif
+</dl>
+% endif
+</%block>
-- 
cgit v1.2.1


From d1e368a22c8b9a9a7b260f7077142233b1a3e189 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Fri, 1 Feb 2013 20:19:12 -0500
Subject: doctool: Update templates to include the actual instance parameter

Rather than fabricating one with a fake name.
---
 giscanner/doctemplates/Python/function.tmpl | 25 ++++++++-----------------
 1 file changed, 8 insertions(+), 17 deletions(-)

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index 467cfcbe..fa705bd0 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -10,19 +10,13 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${node.symbol}</api:name>
-% if node.is_method:
-      <api:arg>
-        <api:type>${node.parent.ctype} *</api:type>
-        <api:name>self</api:name>
-      </api:arg>
-% endif
-% for arg in node.parameters:
+% for arg in node.all_parameters:
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
       <api:arg>
         <api:type>${formatter.format_type(arg.type) | x}</api:type>
-        <api:name>${arg.argname}</api:name>
+        <api:name>${formatter.format_parameter_name(node, arg)}</api:name>
       </api:arg>
 % endif
 % endfor
@@ -30,27 +24,24 @@
 </%block>
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
-% if len(node.parameters) != 0:
+% if len(node.all_parameters) != 0:
 @accepts(\
-${', '.join((formatter.format_type(arg.type) for arg in node.parameters))}\
+${', '.join((formatter.format_type(arg.type) for arg in node.all_parameters))}\
 )
 % endif
 @returns(${formatter.format_type(node.retval.type) | x})
 def \
 ${node.name}(\
-% if node.is_method:
-self, \
-% endif
-${', '.join((arg.argname for arg in node.parameters))}\
+${', '.join((formatter.format_parameter_name(node, arg) for arg in node.all_parameters))}\
 ):
     # Python wrapper for ${node.symbol}()
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.parameters or node.retval:
+% if node.all_parameters or node.retval:
 <dl>
-% for arg, ix in zip(node.parameters, range(len(node.parameters))):
-<dt><p>${arg.argname} :</p></dt>
+% for arg, ix in zip(node.all_parameters, range(len(node.all_parameters))):
+<dt><p>${formatter.format_parameter_name(node, arg)} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
 % if node.retval and node.retval.type.ctype != 'void':
-- 
cgit v1.2.1


From ff80c6d88a28b26576508ab891c9b9da0b13ac49 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Sat, 2 Feb 2013 11:07:42 -0500
Subject: doctool: Don't use zip(range(L))

Instead, remove it entirely (since we don't need the index) or instead
use enumerate().
---
 giscanner/doctemplates/Python/function.tmpl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index fa705bd0..23fde041 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -24,7 +24,7 @@
 </%block>
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
-% if len(node.all_parameters) != 0:
+% if node.all_parameters:
 @accepts(\
 ${', '.join((formatter.format_type(arg.type) for arg in node.all_parameters))}\
 )
@@ -40,7 +40,7 @@ ${', '.join((formatter.format_parameter_name(node, arg) for arg in node.all_para
 <%block name="details">
 % if node.all_parameters or node.retval:
 <dl>
-% for arg, ix in zip(node.all_parameters, range(len(node.all_parameters))):
+% for ix, arg in enumerate(node.all_parameters):
 <dt><p>${formatter.format_parameter_name(node, arg)} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
-- 
cgit v1.2.1


From c9450dc3d7e2f87fa980923594736621f0ecd6ae Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Sat, 2 Feb 2013 11:24:13 -0500
Subject: docwriter: Define a new formatter method for getting params

This will let us gracefully skip over parameters that aren't exposed
by specific language bindings.

It also fixes a bug in the C/Python documentation where we weren't
iterating over the right parameters.
---
 giscanner/doctemplates/Python/function.tmpl | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index 23fde041..356619c3 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -10,7 +10,7 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${node.symbol}</api:name>
-% for arg in node.all_parameters:
+% for arg in formatter.get_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -24,23 +24,23 @@
 </%block>
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
-% if node.all_parameters:
+% if formatter.get_parameters(node):
 @accepts(\
-${', '.join((formatter.format_type(arg.type) for arg in node.all_parameters))}\
+${', '.join((formatter.format_type(arg.type) for arg in formatter.get_parameters(node)))}\
 )
 % endif
 @returns(${formatter.format_type(node.retval.type) | x})
 def \
 ${node.name}(\
-${', '.join((formatter.format_parameter_name(node, arg) for arg in node.all_parameters))}\
+${', '.join((formatter.format_parameter_name(node, arg) for arg in formatter.get_parameters(node)))}\
 ):
     # Python wrapper for ${node.symbol}()
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.all_parameters or node.retval:
+% if formatter.get_parameters(node) or node.retval:
 <dl>
-% for ix, arg in enumerate(node.all_parameters):
+% for ix, arg in enumerate(formatter.get_parameters(node)):
 <dt><p>${formatter.format_parameter_name(node, arg)} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
-- 
cgit v1.2.1


From 3b64a2e808ae25b437c30bec237ada89dc4bcfb3 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Thu, 14 Feb 2013 22:47:10 -0500
Subject: doctool: Fix use of <dl> tag in templates

This isn't legal Mallard
---
 giscanner/doctemplates/Python/function.tmpl | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index 356619c3..d1b57f4e 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -39,15 +39,19 @@ ${', '.join((formatter.format_parameter_name(node, arg) for arg in formatter.get
 </%block>
 <%block name="details">
 % if formatter.get_parameters(node) or node.retval:
-<dl>
+<terms>
 % for ix, arg in enumerate(formatter.get_parameters(node)):
-<dt><p>${formatter.format_parameter_name(node, arg)} :</p></dt>
-<dd>${formatter.format(node, arg.doc)}</dd>
+<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':
-<dt><p>Returns :</p></dt>
-<dd>${formatter.format(node, node.retval.doc)}</dd>
+<item>
+<title><code>Returns</code></title>
+{formatter.format(node, node.retval.doc)}
+</item>
 % endif
-</dl>
+</terms>
 % endif
 </%block>
-- 
cgit v1.2.1


From 9f1b87bb764635eeba7e83bf795844aa49e27d81 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Fri, 15 Feb 2013 06:05:31 -0500
Subject: doctool: Rename page_style to page_kind

---
 giscanner/doctemplates/Python/function.tmpl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index d1b57f4e..e1fc5d94 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -1,9 +1,9 @@
 <%inherit file="/base.tmpl"/>
 <%block name="info">
 % if node.parent is not None:
-    <link type="guide" xref="${namespace.name}.${node.parent.name}" group="${page_style}"/>
+    <link type="guide" xref="${namespace.name}.${node.parent.name}" group="${page_kind}"/>
 % else:
-    <link type="guide" xref="index" group="${page_style}"/>
+    <link type="guide" xref="index" group="${page_kind}"/>
 % endif
     <api:function>
       <api:returns>
-- 
cgit v1.2.1


From d05e20a61d3e381e46fcb306f806566bbbd76312 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" <jstpierre@mecheye.net>
Date: Fri, 15 Feb 2013 06:04:11 -0500
Subject: doctool: Use format_xref to format some links to pages

We don't do a full 100% conversion for all link tags, yet,
because I don't want to break too much here. This may come
later.
---
 giscanner/doctemplates/Python/function.tmpl | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

(limited to 'giscanner/doctemplates/Python/function.tmpl')

diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index e1fc5d94..072a1185 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -1,10 +1,6 @@
 <%inherit file="/base.tmpl"/>
 <%block name="info">
-% if node.parent is not None:
-    <link type="guide" xref="${namespace.name}.${node.parent.name}" group="${page_kind}"/>
-% else:
-    <link type="guide" xref="index" group="${page_kind}"/>
-% endif
+    ${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>
-- 
cgit v1.2.1