Create custom deprecation admonition and use it for all deprecation instances

docs/sphinx/conf.py

@@ -29,7 +29,8 @@ extensions = ['sphinx.ext.todo',
               'sphinx.ext.autodoc',
               'sphinx.ext.autosummary',
               'sphinx.ext.coverage',
-              'availability']
+              'availability',
+              'deprecation']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/sphinx/deprecation.py

@@ -0,0 +1,56 @@
+# Author: Samuel Dunn
+# Intent: Provide an admonishment for wx deprecations
+# Date: 2 / 19 / 18
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from sphinx.locale import _ as convertLocale
+
+class wxdeprecated_node(nodes.Admonition, nodes.Element): pass
+
+def visit_wxdeprecated_node(self, node):
+    self.visit_admonition(node)
+
+def depart_wxdeprecated_node(self, node):
+    self.depart_admonition(node)
+
+
+# Barely more than a copy-paste from sphinx-doc.org/en/1.6/extdev/tutorial.html
+class wxDeprecated(Directive):
+    has_content = True
+
+    def run(self):
+        # docutils will assign magic-members to the instance
+        # before invoking run.
+
+        # convenience reference to the build environment:
+        env = self.state.document.settings.env
+
+        targetid = "deprecated-{}".format(env.new_serialno('deprecated'))
+        targetnode = nodes.target("", "", ids=[targetid])   # ?
+
+        # create a node and pass content and such in.
+        dn = wxdeprecated_node("\n".join(self.content))
+        dn += nodes.title(convertLocale("Deprecated"), convertLocale("Deprecated"))
+
+        # some sphinx magic?
+        self.state.nested_parse(self.content, self.content_offset, dn)
+
+        if not hasattr(env, 'all_deprecations'):
+            env.all_deprecations = []
+
+        env.all_deprecations.append(
+            {
+                'docname'    : env.docname,
+                'lineno'     : self.lineno,
+                'deprecated' : dn.deepcopy(),
+                'target'     : targetnode
+            })
+
+        return [targetnode, dn]
+
+
+def setup(app):
+  app.add_node(wxdeprecated_node, html=(visit_wxdeprecated_node, depart_wxdeprecated_node))
+  app.add_directive('wxdeprecated', wxDeprecated)

etgtools/sphinx_generator.py

@@ -1979,6 +1979,7 @@ class XMLDocString(object):
         else:
             raise Exception('Unhandled docstring kind for %s'%xml_item.__class__.__name__)
 
+
         if hasattr(xml_item, 'deprecated') and xml_item.deprecated and isinstance(xml_item.deprecated, string_base):
             element = et.Element('deprecated', kind='deprecated')
             element.text = VERSION
@@ -2619,11 +2620,7 @@ class XMLDocString(object):
 
         self.Reformat(stream)
 
-        if hasattr(method, 'deprecated') and method.deprecated:
-            text = method.deprecated
-            if isinstance(text, string_base):
-                text = '%s %s\n%s%s\n\n'%('      .. deprecated::', VERSION, ' '*9, text.replace('\n', ' '))
-                stream.write(text)
+        self._dumpDeprecationDirective(method, stream, 6)
 
         possible_py = self.HuntContributedSnippets()
 
@@ -2670,13 +2667,7 @@ class XMLDocString(object):
 
         self.Reformat(stream)
 
-        if hasattr(function, 'deprecated') and function.deprecated:
-            if isinstance(function.deprecated, int):
-                msg = ""
-            else:
-                msg = function.deprecated.replace('\n', ' ')
-            text = '%s %s\n%s%s\n\n'%('   .. deprecated::', VERSION, ' '*6, msg)
-            stream.write(text)
+        self._dumpDeprecationDirective(function, stream, 3)
 
         possible_py = self.HuntContributedSnippets()
 
@@ -2896,6 +2887,23 @@ class XMLDocString(object):
 
         stream.write(docstrings + "\n\n")
 
+    # -----------------------------------------------------------------------
+
+    def _dumpDeprecationDirective(self, defobj, stream, spacing):
+        """
+        Writes the deprecation directive to the stream if necesseary.
+
+        :param BaseDef defobj: The extractor object that is potentially deprecated
+        :param stream: The IO stream to write to
+        :param spacing: indicates how much to pad the directive by, in number of spaces.
+        """
+
+        # all BaseDefs have deprecated now:
+        dep = defobj.deprecated
+        if dep and isinstance(dep, string_base):
+            directive = "{space_a}.. wxdeprecated::\n{space_b}{message}".format(space_a = ' ' * spacing,
+                                                                                space_b = ' ' * (spacing + 3),
+                                                                                message = dep)
 
 # ---------------------------------------------------------------------------
 
@@ -3332,9 +3340,7 @@ class SphinxGenerator(generators.DocsGeneratorBase):
 
         stream.write(newdocs + '\n\n')
 
-        if hasattr(pm, 'deprecated') and pm.deprecated:
-            text = '%s %s\n%s%s\n\n'%('      .. deprecated::', VERSION, ' '*9, pm.deprecated.replace('\n', ' '))
-            stream.write(text)
+        self._dumpDeprecationDirective(pm, stream, 6)
 
         c = self.current_class
         name = c.pyName if c.pyName else removeWxPrefix(c.name)

sphinxtools/constants.py

@@ -52,7 +52,7 @@ PUNCTUATION = '!"#$%\'()*,./:;<=>?@\\^{|}~'
 # Conversion between XML sections and ReST sections
 SECTIONS = [('return'    , ':returns:'),
             ('since'     , '.. versionadded::'),
-            ('deprecated', '.. deprecated::'),
+            ('deprecated', '.. wxdeprecated::'),   # use the custom admonition for deprecation
             ('warning'   , '.. warning::'),
             ('remarks'   , '.. note::'),
             ('remark'    , '.. note::'),