diff options
| author | Philip Chimento <philip.chimento@gmail.com> | 2015-12-06 18:03:15 -0800 |
|---|---|---|
| committer | rockon999 <rockon999@users.noreply.github.com> | 2018-08-06 02:53:45 -0500 |
| commit | 89d655237f9c08a9a83565b2efafe212df41f508 (patch) | |
| tree | 148a9e02e1fe7c0ea094c7ffa5cb3a01ec272648 | |
| parent | 2635fb9fa3e223ae299a4306acf9dc85c6745637 (diff) | |
| download | gobject-introspection-89d655237f9c08a9a83565b2efafe212df41f508.tar.gz | |
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.
| -rw-r--r-- | Makefile-giscanner.am | 1 | ||||
| -rw-r--r-- | giscanner/doctemplates/devdocs/Gjs/_doc.tmpl | 25 | ||||
| -rw-r--r-- | giscanner/doctemplates/devdocs/Gjs/_method.tmpl | 4 | ||||
| -rw-r--r-- | giscanner/doctemplates/devdocs/Gjs/_properties.tmpl | 3 | ||||
| -rw-r--r-- | giscanner/doctemplates/devdocs/Gjs/_signals.tmpl | 5 | ||||
| -rw-r--r-- | giscanner/doctemplates/devdocs/Gjs/base.tmpl | 3 | ||||
| -rw-r--r-- | 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()]) |