Merge pull request #1025 from rmcgibbo/docstring

MAINT: Docstrings

wrappers/python/setup.py

-#
-
 """
 setup.py: Used for building python wrappers for Simbios' OpenMM library.
 """
@@ -15,7 +13,7 @@ MINOR_VERSION_NUM='@OPENMM_MINOR_VERSION@'
 BUILD_INFO='@OPENMM_BUILD_VERSION@'
 IS_RELEASED = False
 
-__author__ = "Randall J. Radmer"
+__author__ = "Peter Eastman"
 __version__ = "%s.%s" % (MAJOR_VERSION_NUM, MINOR_VERSION_NUM)
 
 def reportError(message):
@@ -158,11 +156,11 @@ def buildKeywordDictionary(major_version_num=MAJOR_VERSION_NUM,
     setupKeywords["description"]       = \
     "Python wrapper for OpenMM (a C++ MD package)"
     setupKeywords["long_description"]  = \
-    """OpenMM is a library which provides tools for modern molecular
-    modeling simulation. As a library it can be hooked into any code,
-    allowing that code to do molecular modeling with minimal extra
-    coding (https://simtk.org/home/openmm).  This Python package
-    gives access to the OpenMM API.
+    """OpenMM is a toolkit for molecular simulation. It can be used either as a
+    stand-alone application for running simulations, or as a library you call
+    from your own code. It provides a combination of extreme flexibility
+    (through custom forces and integrators), openness, and high performance
+    (especially on recent GPUs) that make it truly unique among simulation codes.
     """
 
     define_macros = [('MAJOR_VERSION', major_version_num),

wrappers/python/simtk/openmm/__init__.py

+"""OpenMM is a toolkit for molecular simulation. It can be used either as a
+stand-alone application for running simulations, or as a library you call
+from your own code. It provides a combination of extreme flexibility
+(through custom forces and integrators), openness, and high performance
+(especially on recent GPUs) that make it truly unique among simulation codes.
 """
-Package simtk.openmm
-
-This package wraps the simtk.openmm.openmm module.
-When imported, it loads the swig module and then does some magic
-to make the POSIX function "dlopen" work on Linux.
-It also tries to load any plugin modules it can find.
-"""
-
-__author__ = "Randall J. Radmer"
+__author__ = "Peter Eastman"
 
 import os, os.path
 import sys

wrappers/python/src/swig_doxygen/OpenMM.i

-
-%define DOCSTRING
-"PyOpenMM is a Python application programming interface (API) to be
-used for performing molecular dynamics (MD) simulations on various
-computer architectures (including GPUs).  It is implemented in Python
-and C/C++, and provides a Python interface to the OpenMM libraries
-(see https://simtk.org/home/openmm for OpenMM details).  The primary
-motivation for creating PyOpenMM is to make it possible to write
-GPU-accelerated MD code in pure Python.
-
-See https://simtk.org/home/pyopenmm for details"
-%enddef
-
-%module (docstring=DOCSTRING) openmm
+%module openmm
 
 %include "factory.i"
 %include "std_string.i"

wrappers/python/src/swig_doxygen/swigInputBuilder.py

@@ -13,7 +13,45 @@ import getopt
 import re
 import xml.etree.ElementTree as etree
 
-#
+try:
+    from html.parser import HTMLParser
+except ImportError:
+    # python 2
+    from HTMLParser import HTMLParser
+
+
+def striphtmltags(s):
+    """Strip a couple html tags used inside docstrings in the C++ source
+    to produce something more easily read as plain text.
+    """
+    class ConvertLists(HTMLParser):
+        def reset(self):
+            HTMLParser.reset(self)
+            self.out = []
+
+        def handle_starttag(self, tag, attrs):
+            if tag == 'li':
+                self.out.append('\n - ')
+        def handle_data(self, data):
+            self.out.append(data.strip())
+
+    convertlists = ConvertLists()
+
+    def replace_ul_tags(m):
+        a, b = m.span()
+        sub = s[a:b]
+
+        convertlists.reset()
+        convertlists.feed(sub)
+        return '\n%s\n\n' % ''.join(convertlists.out)
+
+    s = s.replace('<i>', '_').replace('</i>', '_')
+    s = s.replace('<b>', '*').replace('</b>', '*')
+
+    s = re.sub('\s*(<ul>.*</ul>\s*)', replace_ul_tags, s, flags=re.MULTILINE | re.DOTALL)
+
+    return s
+
 
 INDENT = "   ";
 
@@ -266,6 +304,7 @@ class SwigInputBuilder:
                 dNode = classNode.find('detaileddescription')
                 if dNode is not None:
                     docstring = getNodeText(dNode).strip().replace('"', '\\"')
+                    docstring = striphtmltags(docstring)
                     self.fOutDocstring.write('%%feature("docstring") %s "%s";\n' % (className, docstring))
             self.fOut.write("class %s" % className)
             if className in self.configModule.MISSING_BASE_CLASSES: