[gobject-introspection/wip/docs-json: 1/2] docwriter: Format markdown in doc comments

[Tomeu Vizoso <tomeuv src gnome org>]

commit 45614cc6d97b030ff36e980d2614a4b925ac7c02
Author: Tomeu Vizoso <tomeu vizoso collabora com>
Date:   Sat May 3 10:54:38 2014 +0200

    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.

 configure.ac                                       |   13 ++++++++++---
 giscanner/docwriter.py                             |    6 +++---
 .../Regress.test_value_return.page                 |    2 +-
 .../Regress.test_value_return.page                 |    2 +-
 .../Regress.test_value_return.page                 |    2 +-
 tests/scanner/Regress-1.0-expected.gir             |    1 +
 tests/scanner/regress.c                            |    2 ++
 7 files changed, 19 insertions(+), 9 deletions(-)
---
diff --git a/configure.ac b/configure.ac
index 96da585..f7c5720 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 d888c81..49cdb8e 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 25d1f71..5a784dd 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 d843d28..7d19967 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 d35a11a..adaae9a 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 82c11d3..b7b6610 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 1bad36e..8760d76 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 *