Merge pull request #762 from mesalu/admonish_deprecation

Admonish deprecations

docs/sphinx/_static/css/phoenix.css

@@ -478,6 +478,16 @@ div.availability {
     background: #e8f7c4;
 }
 
+div.wxdeprecated {
+  background-color: #ffe6c3;
+  border: 1px solid #edc388;
+  text-align: left;
+  background-image: url('../images/sphinxdocs/warning.png');
+  background-repeat: no-repeat;
+  background-position: 5px 5px;
+  padding-left: 33px;
+}
+
 
  p.admonition-title {
    margin: 10px 10px 5px 0px;

docs/sphinx/availability.py

@@ -12,7 +12,7 @@ from docutils import nodes
 from sphinx.locale import _
 from sphinx.environment import NoUri
 from sphinx.util.nodes import set_source_info
-from sphinx.util.compat import Directive, make_admonition
+from docutils.parsers.rst import Directive
 
 # ----------------------------------------------------------------------- #
 class availability_node(nodes.Admonition, nodes.Element): pass
@@ -42,13 +42,12 @@ class Availability(Directive):
         targetid = 'index-%s' % env.new_serialno('index')
         targetnode = nodes.target('', '', ids=[targetid])
 
-        ad = make_admonition(availability_node, self.name, [_('Availability')], self.options,
-                             self.content, self.lineno, self.content_offset,
-                             self.block_text, self.state, self.state_machine)
-        set_source_info(self, ad[0])
-        return [targetnode] + ad
+        avail_node = availability_node('\n'.join(self.content))
+        avail_node += nodes.title(_("Availability"), _("Availability"))
 
+        self.state.nested_parse(self.content, self.content_offset, avail_node)
 
+        return [targetnode, avail_node]
 
 # ----------------------------------------------------------------------- #
 
@@ -165,6 +164,11 @@ def purge_availabilities(app, env, docname):
 # ----------------------------------------------------------------------- #
 
 def visit_availability_node(self, node):
+    classes = node.get('classes')
+    for c in ("admonition", "availability"):
+        if not c in classes:
+            classes.append(c)
+
     self.visit_admonition(node)
 
 

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,60 @@
+# 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):
+    for c in ('admonition', 'wxdeprecated'):
+        if not c in node.get('classes'):
+            node.get('classes').append(c)
+
+    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"))
+
+        # Parse all sub-elements into deprecation_node instance
+        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)

docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst

@@ -169,8 +169,8 @@ admonitions:
    world, this may also indicate that a particular widget is not
    supported under one or more platforms;
 
-3. ``.. deprecated::`` : used to mark deprecated methods, classes or
-   functions;
+3. ``.. wxdeprecated::`` : used to mark deprecated methods, classes or
+   functions. Please avoid using ``.. deprecated``. ;
 
 4. ``.. availability::`` : normally employed to make the user
    understand on which platform(s) a particular functionality is

etgtools/sphinx_generator.py

@@ -1067,7 +1067,7 @@ class Section(Node):
 
         elif section_type == 'deprecated':
             # Special treatment for deprecated, wxWidgets devs do not put the version number
-            text = '%s\n%s%s'%(VERSION, sub_spacer, text.lstrip('Deprecated'))
+            text = '\n%s%s'%(sub_spacer, text.lstrip('Deprecated'))
 
         elif section_type == 'par':
             # Horrible hack... Why is there a </para> end tag inside the @par tag???
@@ -1979,9 +1979,12 @@ class XMLDocString(object):
         else:
             raise Exception('Unhandled docstring kind for %s'%xml_item.__class__.__name__)
 
+        # Some of the Exctractors (xml item) will set deprecated themselves, in which case it is set as a
+        # non-empty string. In such cases, this branch will insert a deprecated section into the xml tree
+        # so that the Node Tree (see classes above) will generate the deprecated  tag on their own in self.RecurseXML
         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
+            element.text = xml_item.deprecated
 
             deprecated_section = Section(element, None, self.kind, self.is_overload, self.share_docstrings)
             self.root.AddSection(deprecated_section)
@@ -2619,12 +2622,6 @@ 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)
-
         possible_py = self.HuntContributedSnippets()
 
         if possible_py:
@@ -2670,14 +2667,6 @@ 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)
-
         possible_py = self.HuntContributedSnippets()
 
         if possible_py:
@@ -2896,7 +2885,6 @@ class XMLDocString(object):
 
         stream.write(docstrings + "\n\n")
 
-
 # ---------------------------------------------------------------------------
 
 class SphinxGenerator(generators.DocsGeneratorBase):
@@ -3332,10 +3320,6 @@ 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)
-
         c = self.current_class
         name = c.pyName if c.pyName else removeWxPrefix(c.name)
         imm = ItemModuleMap()

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::'),