[gobject-introspection: 9/30] devdocs: Generate versioning notes

[Christoph Reiter <creiter src gnome org>]

commit 89d655237f9c08a9a83565b2efafe212df41f508
Author: Philip Chimento <philip chimento gmail com>
Date:   Sun Dec 6 18:03:15 2015 -0800

    devdocs: Generate versioning notes
    
    For GIR nodes with version annotations, such as "Since:", "Deprecated:",
    and "Stability:", we generate stability notes at the top of each node's
    documentation. These notes are given the CSS class "versioning-note" so
    that we can format them nicely in DevDocs.

 Makefile-giscanner.am                              |  1 +
 giscanner/doctemplates/devdocs/Gjs/_doc.tmpl       | 25 ++++++++++++++++++++++
 giscanner/doctemplates/devdocs/Gjs/_method.tmpl    |  4 +++-
 .../doctemplates/devdocs/Gjs/_properties.tmpl      |  3 ++-
 giscanner/doctemplates/devdocs/Gjs/_signals.tmpl   |  5 ++---
 giscanner/doctemplates/devdocs/Gjs/base.tmpl       |  3 ++-
 giscanner/docwriter.py                             |  2 ++
 7 files changed, 37 insertions(+), 6 deletions(-)
---
diff --git a/Makefile-giscanner.am b/Makefile-giscanner.am
index 4336a140..2879ab20 100644
--- a/Makefile-giscanner.am
+++ b/Makefile-giscanner.am
@@ -107,6 +107,7 @@ nobase_dist_template_DATA =         \
        giscanner/doctemplates/mallard/Gjs/record.tmpl          \
        giscanner/doctemplates/mallard/Gjs/signal.tmpl          \
        giscanner/doctemplates/mallard/Gjs/vfunc.tmpl           \
+       giscanner/doctemplates/devdocs/Gjs/_doc.tmpl            \
        giscanner/doctemplates/devdocs/Gjs/_index.tmpl          \
        giscanner/doctemplates/devdocs/Gjs/_method.tmpl         \
        giscanner/doctemplates/devdocs/Gjs/_methods.tmpl        \
diff --git a/giscanner/doctemplates/devdocs/Gjs/_doc.tmpl b/giscanner/doctemplates/devdocs/Gjs/_doc.tmpl
new file mode 100644
index 00000000..0e132b44
--- /dev/null
+++ b/giscanner/doctemplates/devdocs/Gjs/_doc.tmpl
@@ -0,0 +1,25 @@
+<%def name="format_documentation(node)">
+  % if node.version:
+    <p class="versioning-note">
+      New in version ${node.version}.
+      ${formatter.format_inline(node, node.version_doc)}
+    </p>
+  % endif
+  % if node.deprecated:
+    <p class="versioning-note">
+      Deprecated since ${node.deprecated}.
+      ${formatter.format_inline(node, node.deprecated_doc)}
+    </p>
+  % endif
+  % if node.stability:
+    ## Not sure what this looks like in the wild
+    <p class="versioning-note">
+      Stability: ${node.stability}.
+      ${formatter.format_inline(node, node.stability_doc)}
+    </p>
+  % endif
+
+  % if node.doc:
+    ${formatter.format(node, node.doc)}
+  % endif
+</%def>
diff --git a/giscanner/doctemplates/devdocs/Gjs/_method.tmpl b/giscanner/doctemplates/devdocs/Gjs/_method.tmpl
index 0374ba40..3e4d596e 100644
--- a/giscanner/doctemplates/devdocs/Gjs/_method.tmpl
+++ b/giscanner/doctemplates/devdocs/Gjs/_method.tmpl
@@ -1,3 +1,5 @@
+<%namespace name="doc" file="_doc.tmpl"/>
+
 <%def name="describe_parameters(m, static=False, virtual=False)">
   <dl>
     % if static:
@@ -44,5 +46,5 @@
     -->(${formatter.format_in_parameters(m)})
   </h3>
   ${describe_parameters(m, static, virtual)}
-  ${formatter.format(m, m.doc)}
+  ${doc.format_documentation(m)}
 </%def>
diff --git a/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl 
b/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl
index ef9913aa..876beb83 100644
--- a/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl
+++ b/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl
@@ -1,3 +1,4 @@
+<%namespace name="doc" file="_doc.tmpl"/>
 <%!
   def dash_to_underscore(string):
     return '_'.join(string.split('-'))
@@ -28,7 +29,7 @@
       <dd>${formatter.format_property_flags(p)}</dd>
     </dl>
     % if p.doc:
-      ${formatter.format(node, p.doc)}
+      ${doc.format_documentation(p)}
     % endif
   % endfor
 % endif
diff --git a/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl 
b/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl
index 4065df83..073d73f2 100644
--- a/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl
+++ b/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl
@@ -1,3 +1,4 @@
+<%namespace name="doc" file="_doc.tmpl"/>
 <%namespace name="method" file="_method.tmpl"/>
 % if getattr(node, 'signals', []):
   <h2>Signal Details</h2>
@@ -13,8 +14,6 @@
       <dd>${formatter.format_signal_flags(s)}</dd>
       ${method.describe_parameters(s)}
     </dl>
-    % if s.doc:
-      ${formatter.format(node, s.doc)}
-    % endif
+    ${doc.format_documentation(s)}
   % endfor
 % endif
diff --git a/giscanner/doctemplates/devdocs/Gjs/base.tmpl b/giscanner/doctemplates/devdocs/Gjs/base.tmpl
index 91ffa105..f35bc4c7 100644
--- a/giscanner/doctemplates/devdocs/Gjs/base.tmpl
+++ b/giscanner/doctemplates/devdocs/Gjs/base.tmpl
@@ -1,10 +1,11 @@
+<%namespace name="doc" file="_doc.tmpl"/>
 <html>
 <body>
   <section>
     <h1 class="${page_kind}">${formatter.format_page_name(node)}</h1>
     <%include file="_index.tmpl"/>
     <h2>Details</h2>
-    ${formatter.format(node, node.doc)}
+    ${doc.format_documentation(node)}
     <%include file="_staticmethods.tmpl"/>
     <%include file="_methods.tmpl"/>
     <%include file="_vfuncs.tmpl"/>
diff --git a/giscanner/docwriter.py b/giscanner/docwriter.py
index e1d3149e..0d55936c 100644
--- a/giscanner/docwriter.py
+++ b/giscanner/docwriter.py
@@ -1160,6 +1160,8 @@ class DevDocsFormatterGjs(DocFormatterGjs):
                                          pluralize=pluralize)
 
     def format_inline(self, node, para):
+        if para is None:
+            return ''
         cleaned_up_gtkdoc = super(DevDocsFormatterGjs, self).format_inline(node, para)
         return markdown.markdown(cleaned_up_gtkdoc, extensions=[InlineMarkdown()])