docwriter: Format markdown in doc comments

Libraries in the GNOME platform are currently being moved
from Docbook to Markdown. This produces HTML at present instead
of Mallard, but in coming commits Mallard will be removed so this
won't be an issue.

This introduces a dependency on python-markdown.

7 files changed, 19 insertions, 9 deletions

diff --git a/configure.ac b/configure.ac
index 96da5852..f7c57201 100644
--- a/configure.ac
+++ b/configure.ac
@@ -269,13 +269,20 @@ dnl an external dependency
 AC_ARG_ENABLE(doctool,[  --disable-doctool           disable g-ir-doctool ],,enable_doctool=auto)
 AS_IF([ test x$enable_doctool != xno], [
    AM_CHECK_PYMOD(mako,,have_python_mako=yes,have_python_mako=no)
+   AM_CHECK_PYMOD(markdown,,have_python_markdown=yes,have_python_markdown=no)
 ])
-AS_IF([ test x$enable_doctool = xauto && test x$have_python_mako = xyes ],
+AS_IF([ test x$enable_doctool = xauto &&
+        test x$have_python_mako = xyes &&
+        test x$have_python_markdown = xyes ],
       [ enable_doctool=yes ],
-      [ test x$enable_doctool = xauto && test x$have_python_mako = xno ],
+      [ test x$enable_doctool = xauto &&
+        (test x$have_python_mako = xno ||
+         test x$have_python_markdown = xno) ],
       [ enable_doctool=no ],
       [ test x$enable_doctool = xyes && test x$have_python_mako = xno ],
-      [ AC_MSG_ERROR([Python mako module not found]) ])
+      [ AC_MSG_ERROR([Python mako module not found]) ],
+      [ test x$enable_doctool = xyes && test x$have_python_markdown = xno ],
+      [ AC_MSG_ERROR([Python markdown module not found]) ])
 AM_CONDITIONAL(BUILD_DOCTOOL, test x$enable_doctool != xno)
 
 # Glib documentation
diff --git a/giscanner/docwriter.py b/giscanner/docwriter.py
index d888c81b..49cdb8e2 100644
--- a/giscanner/docwriter.py
+++ b/giscanner/docwriter.py
@@ -27,6 +27,7 @@ import tempfile
 
 from xml.sax import saxutils
 from mako.lookup import TemplateLookup
+import markdown
 
 from . import ast, xmlwriter
 from .utils import to_underscores
@@ -200,9 +201,8 @@ class DocFormatter(object):
 
         result = ''
         for para in doc.split('\n\n'):
-            result += '  <p>'
-            result += self.format_inline(node, para)
-            result += '</p>'
+            result += '  '
+            result += markdown.markdown(self.format_inline(node, para))
         return result
 
     def _resolve_type(self, ident):
diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.test_value_return.page b/tests/scanner/Regress-1.0-C-expected/Regress.test_value_return.page
index 25d1f71c..5a784dd5 100644
--- a/tests/scanner/Regress-1.0-C-expected/Regress.test_value_return.page
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.test_value_return.page
@@ -22,7 +22,7 @@
   <synopsis><code mime="text/x-csrc">
 const GValue* regress_test_value_return (int i);
   </code></synopsis>
-
+  <p>This is a <em>test</em> of <strong>Markdown</strong> formatting within a comment.</p>
 
 <terms>
 <item>
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_value_return.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_value_return.page
index d843d286..7d19967e 100644
--- a/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_value_return.page
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_value_return.page
@@ -24,7 +24,7 @@ function test_value_return(i: Number(gint)): Any {
     // Gjs wrapper for regress_test_value_return()
 }
   </code></synopsis>
-
+  <p>This is a <em>test</em> of <strong>Markdown</strong> formatting within a comment.</p>
 
 <terms>
 <item>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.test_value_return.page b/tests/scanner/Regress-1.0-Python-expected/Regress.test_value_return.page
index d35a11af..adaae9a5 100644
--- a/tests/scanner/Regress-1.0-Python-expected/Regress.test_value_return.page
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.test_value_return.page
@@ -25,7 +25,7 @@
 def test_value_return(i):
     # Python wrapper for regress_test_value_return()
   </code></synopsis>
-
+  <p>This is a <em>test</em> of <strong>Markdown</strong> formatting within a comment.</p>
 
 <terms>
 <item>
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index 82c11d32..b7b66100 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -6532,6 +6532,7 @@ https://bugzilla.gnome.org/show_bug.cgi?id=685399</doc>
     </function>
     <function name="test_value_return"
               c:identifier="regress_test_value_return">
+      <doc xml:space="preserve">This is a _test_ of **Markdown** formatting within a comment.</doc>
       <return-value transfer-ownership="none">
         <doc xml:space="preserve">the int wrapped in a GValue.</doc>
         <type name="GObject.Value" c:type="const GValue*"/>
diff --git a/tests/scanner/regress.c b/tests/scanner/regress.c
index 1bad36e3..8760d763 100644
--- a/tests/scanner/regress.c
+++ b/tests/scanner/regress.c
@@ -268,6 +268,8 @@ static GValue value;
  * regress_test_value_return:
  * @i: an int
  *
+ * This is a _test_ of **Markdown** formatting within a comment.
+ *
  * Return value: (transfer none): the int wrapped in a GValue.
  */
 const GValue *