mal2html-api: Basic Python support

10 files changed, 240 insertions, 11 deletions

diff --git a/test/api/func1.page b/test/api/c_func1.page
index c2084415..9ca0b460 100644
--- a/test/api/func1.page
+++ b/test/api/c_func1.page
@@ -1,13 +1,13 @@
 <page xmlns="http://projectmallard.org/1.0/"
       xmlns:api="http://projectmallard.org/experimental/api/"
       type="topic"
-      id="func1">
+      id="c_func1">
 
 <info>
   <api:function>
     <api:name>function_1</api:name>
   </api:function>
-  <link type="guide" xref="index"/>
+  <link type="guide" xref="index" group="c"/>
 </info>
 
 <title>Function #1</title>
diff --git a/test/api/func2.page b/test/api/c_func2.page
index 64d30dc8..4f90490d 100644
--- a/test/api/func2.page
+++ b/test/api/c_func2.page
@@ -1,7 +1,7 @@
 <page xmlns="http://projectmallard.org/1.0/"
       xmlns:api="http://projectmallard.org/experimental/api/"
       type="topic"
-      id="func2">
+      id="c_func2">
 
 <info>
   <api:function>
@@ -26,7 +26,7 @@
       <api:name>...</api:name>
     </api:arg>
   </api:function>
-  <link type="guide" xref="index"/>
+  <link type="guide" xref="index" group="c"/>
 </info>
 
 <title>A Long Function Name</title>
diff --git a/test/api/func3.page b/test/api/c_func3.page
index bf4cf216..3108a444 100644
--- a/test/api/func3.page
+++ b/test/api/c_func3.page
@@ -1,16 +1,16 @@
 <page xmlns="http://projectmallard.org/1.0/"
       xmlns:api="http://projectmallard.org/experimental/api/"
       type="topic"
-      id="func3">
+      id="c_func3">
 
 <info>
   <api:function>
     <api:returns>
-      <api:type><link xref="type1" role="api:name"/></api:type>
+      <api:type><link xref="c_type1" role="api:name"/></api:type>
     </api:returns>
     <api:name>function_3</api:name>
   </api:function>
-  <link type="guide" xref="index"/>
+  <link type="guide" xref="index" group="c"/>
 </info>
 
 <title>Function #3</title>
diff --git a/test/api/type1.page b/test/api/c_type1.page
index adbf886f..73da248d 100644
--- a/test/api/type1.page
+++ b/test/api/c_type1.page
@@ -1,13 +1,13 @@
 <page xmlns="http://projectmallard.org/1.0/"
       xmlns:api="http://projectmallard.org/experimental/api/"
       type="topic"
-      id="type1">
+      id="c_type1">
 
 <info>
-  <link type="guide" xref="index"/>
   <api:type>
     <api:name>type1</api:name>
   </api:type>
+  <link type="guide" xref="index" group="c"/>
 </info>
 
 <title>Type #1</title>
diff --git a/test/api/index.page b/test/api/index.page
index a6800a2a..61bbc5f4 100644
--- a/test/api/index.page
+++ b/test/api/index.page
@@ -5,11 +5,11 @@
 
 <title>API Extension Test</title>
 
-<links type="topic" api:mime="text/x-csrc">
+<links type="topic" groups="c" api:mime="text/x-csrc">
   <title>C</title>
 </links>
 
-<links type="topic" api:mime="text/x-python">
+<links type="topic" groups="py" api:mime="text/x-python">
   <title>Python</title>
 </links>
 
diff --git a/test/api/py_func1.page b/test/api/py_func1.page
new file mode 100644
index 00000000..c2817ad9
--- /dev/null
+++ b/test/api/py_func1.page
@@ -0,0 +1,15 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="py_func1">
+
+<info>
+  <api:function>
+    <api:name>py_func_1</api:name>
+  </api:function>
+  <link type="guide" xref="index" group="py"/>
+</info>
+
+<title>Function #1</title>
+
+</page>
diff --git a/test/api/py_func2.page b/test/api/py_func2.page
new file mode 100644
index 00000000..ef0c91c5
--- /dev/null
+++ b/test/api/py_func2.page
@@ -0,0 +1,27 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="py_func2">
+
+<info>
+  <api:function>
+    <api:returns>
+      <api:type>sometype</api:type>
+    </api:returns>
+    <api:name>py_func_2</api:name>
+    <api:arg>
+      <api:name>arg1</api:name>
+    </api:arg>
+    <api:arg>
+      <api:name>arg2</api:name>
+    </api:arg>
+    <api:arg>
+      <api:name>**kwargs</api:name>
+    </api:arg>
+  </api:function>
+  <link type="guide" xref="index" group="py"/>
+</info>
+
+<title>Function #2</title>
+
+</page>
diff --git a/test/api/py_func3.page b/test/api/py_func3.page
new file mode 100644
index 00000000..5d61b20a
--- /dev/null
+++ b/test/api/py_func3.page
@@ -0,0 +1,23 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="py_func3">
+
+<info>
+  <api:function>
+    <api:name>py_func_3</api:name>
+    <api:arg>
+      <api:type>type1</api:type>
+      <api:name>arg1</api:name>
+    </api:arg>
+    <api:arg>
+      <api:type><link xref="py_type1" role="api:name"/></api:type>
+      <api:name>arg2</api:name>
+    </api:arg>
+  </api:function>
+  <link type="guide" xref="index" group="py"/>
+</info>
+
+<title>Function #2</title>
+
+</page>
diff --git a/test/api/py_type1.page b/test/api/py_type1.page
new file mode 100644
index 00000000..9a5384cd
--- /dev/null
+++ b/test/api/py_type1.page
@@ -0,0 +1,15 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="py_type1">
+
+<info>
+  <api:type>
+    <api:name>type1</api:name>
+  </api:type>
+  <link type="guide" xref="index" group="py"/>
+</info>
+
+<title>Python Type #1</title>
+
+</page>
diff --git a/xslt/mallard/html/mal2html-api.xsl b/xslt/mallard/html/mal2html-api.xsl
index e7bdee48..b617ab76 100644
--- a/xslt/mallard/html/mal2html-api.xsl
+++ b/xslt/mallard/html/mal2html-api.xsl
@@ -65,6 +65,12 @@ elements. It should be called by an appropriate template that handles the
         <xsl:with-param name="links" select="$links"/>
       </xsl:call-template>
     </xsl:when>
+    <xsl:when test="$node/@api:mime = 'text/x-python'">
+      <xsl:call-template name="mal2html.api.links.py">
+        <xsl:with-param name="node" select="$node"/>
+        <xsl:with-param name="links" select="$links"/>
+      </xsl:call-template>
+    </xsl:when>
     <xsl:otherwise>
       <xsl:call-template name="mal2html.links.ul">
         <xsl:with-param name="node" select="$node"/>
@@ -258,4 +264,147 @@ contains an #{api:function} element in its #{info}.
   </div>
 </xsl:template>
 
+
+<!--**==========================================================================
+mal2html.api.links.py
+Output links as a synopsis for the Python programming language.
+$node: A #{links} element to link from.
+$links: A list of links, as from a template in !{mal-link}.
+
+This template outputs links as a synopsis in the Python programming language.
+It is called by *{mal2html.api.links} when the #{api:mime} attribute of ${node}
+is #{text/x-python}. The target nodes of ${links} are expected to have appropriate
+API metadata elements in their #{info} elements. Links to targets without correct
+API metadata are output with *{mal2html.links.ul} after the synopsis.
+
+This template calls other templates to format each link, based on what type of
+API the target node is declared as.
+
+This template handles link sorting, and may have specialized sorting using the
+API metadata of the target nodes.
+-->
+<xsl:template name="mal2html.api.links.py">
+  <xsl:param name="node"/>
+  <xsl:param name="links"/>
+  <xsl:variable name="apilinks_">
+    <xsl:for-each select="$links">
+      <xsl:variable name="link" select="."/>
+      <xsl:for-each select="$mal.cache">
+        <xsl:variable name="target" select="key('mal.cache.key', $link/@xref)"/>
+        <xsl:variable name="apiname" select="$target/mal:info/api:*/api:name[1]"/>
+        <xsl:for-each select="$link">
+          <xsl:copy>
+            <xsl:copy-of select="@*"/>
+            <xsl:copy-of select="*"/>
+            <xsl:copy-of select="$apiname"/>
+          </xsl:copy>
+        </xsl:for-each>
+      </xsl:for-each>
+    </xsl:for-each>
+  </xsl:variable>
+  <xsl:variable name="apilinks" select="exsl:node-set($apilinks_)/*"/>
+  <xsl:variable name="out_">
+    <xsl:for-each select="$apilinks">
+      <xsl:sort select="api:name"/>
+      <xsl:sort data-type="number" select="@groupsort"/>
+      <xsl:sort select="mal:title[@type = 'sort']"/>
+      <xsl:variable name="link" select="."/>
+      <xsl:for-each select="$mal.cache">
+        <xsl:variable name="target" select="key('mal.cache.key', $link/@xref)"/>
+        <xsl:choose>
+          <xsl:when test="$target/mal:info/api:function/api:name">
+            <xsl:call-template name="mal2html.api.links.py.function">
+              <xsl:with-param name="node" select="$node"/>
+              <xsl:with-param name="links" select="$links"/>
+              <xsl:with-param name="link" select="$link"/>
+              <xsl:with-param name="target" select="$target"/>
+            </xsl:call-template>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:copy-of select="$link"/>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:for-each>
+    </xsl:for-each>
+  </xsl:variable>
+  <xsl:variable name="out" select="exsl:node-set($out_)"/>
+  <xsl:if test="$out/*[not(self::mal:link)]">
+    <div class="synopsis">
+      <pre class="contents">
+        <xsl:copy-of select="$out/*[not(self::mal:link)]"/>
+      </pre>
+    </div>
+  </xsl:if>
+  <xsl:if test="$out/mal:link">
+    <xsl:call-template name="mal2html.links.ul">
+      <xsl:with-param name="node" select="$node"/>
+      <xsl:with-param name="links" select="$out/mal:link"/>
+    </xsl:call-template>
+  </xsl:if>
+</xsl:template>
+
+
+<!--**==========================================================================
+mal2html.api.links.py.function
+Output a link as a function for a synopsis in Python.
+$node: A #{links} element to link from.
+$links: A list of links, as from a template in !{mal-link}.
+$link: The #{mal:link} element from ${links} to process.
+$target: The node pointed to by ${link}.
+
+This template formats a link formatted as a function for a synopsis in the Python
+programming language. It is called by *{mal2html.api.links.py} when the ${target}
+contains an #{api:function} element in its #{info}.
+-->
+<xsl:template name="mal2html.api.links.py.function">
+  <xsl:param name="node"/>
+  <xsl:param name="links"/>
+  <xsl:param name="link"/>
+  <xsl:param name="target"/>
+  <xsl:variable name="function" select="$target/mal:info/api:function"/>
+  <div class="{$link/@class}">
+    <xsl:for-each select="$link/@*">
+      <xsl:if test="starts-with(name(.), 'data-')">
+        <xsl:copy-of select="."/>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:text>def </xsl:text>
+    <xsl:variable name="name">
+      <xsl:apply-templates mode="mal2html.inline.mode" select="$function/api:name/node()"/>
+    </xsl:variable>
+    <a>
+      <xsl:attribute name="href">
+        <xsl:call-template name="mal.link.target">
+          <xsl:with-param name="node" select="$node"/>
+          <xsl:with-param name="xref" select="$link/@xref"/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:attribute name="title">
+        <xsl:call-template name="mal.link.tooltip">
+          <xsl:with-param name="node" select="$node"/>
+          <xsl:with-param name="xref" select="$link/@xref"/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:copy-of select="$name"/>
+    </a>
+    <xsl:text>(</xsl:text>
+    <xsl:for-each select="$function/api:arg">
+      <xsl:if test="position() != 1">
+        <xsl:text>, </xsl:text>
+      </xsl:if>
+      <xsl:apply-templates mode="mal2html.inline.mode" select="api:name/node()"/>
+      <xsl:if test="api:type">
+        <xsl:text>: </xsl:text>
+        <xsl:apply-templates mode="mal2html.inline.mode" select="api:type/node()"/>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:text>)</xsl:text>
+    <xsl:if test="$function/api:returns/api:type">
+      <xsl:text> -> </xsl:text>
+      <xsl:apply-templates mode="mal2html.inline.mode" select="$function/api:returns/api:type/node()"/>
+    </xsl:if>
+    <xsl:text>&#x000A;</xsl:text>
+  </div>
+</xsl:template>
+
 </xsl:stylesheet>