Fixed deprecation warnings in Python API docs

docs-source/api-python/process-docstring.py

@@ -2,7 +2,7 @@ import re
 
 def process_docstring(app, what, name, obj, options, lines):
     """This hook edits the docstrings to replace "<tt><pre>" html tags
-    with sphinx directives.
+    and deprecated markers with sphinx directives.
     """
     def repl(m):
         s = m.group(1)
@@ -10,15 +10,19 @@ def process_docstring(app, what, name, obj, options, lines):
             s = linesep + s
         newline = '.. code-block:: c++' + linesep
         return newline + '    ' + s.replace(linesep, linesep + '    ')
-
-    if name == 'simtk.openmm.openmm.CustomTorsionForce':
-         print(lines)
+    def repl2(m):
+        s = m.group(1)
+        if not s.startswith(linesep):
+            s = linesep + s
+        newline = '|LINEBREAK|.. admonition:: Deprecated' + linesep
+        return newline + '    ' + s.replace(linesep, linesep + '    ')
 
     linesep = '|LINEBREAK|'
     joined = linesep.join(lines)
 
     joined = re.sub(r'<tt><pre>((|LINEBREAK|)?.*?)</pre></tt>', repl, joined)
     joined = re.sub(r'<tt>(.*?)</tt>', repl, joined)
+    joined = re.sub(r'@deprecated(.*?\|LINEBREAK\|)', repl2, joined, flags=re.IGNORECASE)
     lines[:] = [(l if not l.isspace() else '') for l in joined.split(linesep)]
 
 

wrappers/python/simtk/openmm/app/modeller.py

@@ -186,8 +186,7 @@ class Modeller(object):
     def convertWater(self, model='tip3p'):
         """Convert all water molecules to a different water model.
 
-        @deprecated Use addExtraParticles() instead.  It performs the same
-        function but in a more general way.
+        @deprecated Use addExtraParticles() instead.  It performs the same function but in a more general way.
 
         Parameters
         ----------

wrappers/python/src/swig_doxygen/swigInputBuilder.py

@@ -74,6 +74,11 @@ def getNodeText(node):
             s = "%s%s\n\n" % (s, getNodeText(n))
         elif n.tag == "ref":
             s = "%s%s" % (s, getNodeText(n))
+        elif n.tag == "xrefsect":
+            title = n.find("xreftitle")
+            description = n.find("xrefdescription")
+            if title is not None and description is not None and getNodeText(title).lower() == "deprecated":
+                s = "%s\n@deprecated %s\n\n" % (s, getNodeText(description))
         else:
             if n.tag in docTags:
                 tag = docTags[n.tag]

wrappers/python/src/swig_doxygen/swig_lib/python/extend.i

@@ -322,14 +322,14 @@ Parameters:
 }
 
 %extend OpenMM::XmlSerializer {
-  %feature(docstring, "This method exists only for backward compatibility. @deprecated Use serialize() instead.") serializeSystem;
+  %feature(docstring, "This method exists only for backward compatibility.\n@deprecated Use serialize() instead.") serializeSystem;
   static std::string serializeSystem(const OpenMM::System* object) {
       std::stringstream ss;
       OpenMM::XmlSerializer::serialize<OpenMM::System>(object, "System", ss);
       return ss.str();
   }
 
-  %feature(docstring, "This method exists only for backward compatibility. @deprecated Use deserialize() instead.") deserializeSystem;
+  %feature(docstring, "This method exists only for backward compatibility.\n@deprecated Use deserialize() instead.") deserializeSystem;
   %newobject deserializeSystem;
   static OpenMM::System* deserializeSystem(const char* inputString) {
       std::stringstream ss;