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),
@@ -181,7 +179,7 @@ def buildKeywordDictionary(major_version_num=MAJOR_VERSION_NUM,
             for ii in range(len(libraries)):
                 libraries[ii]="%s_d" % libraries[ii]
                 sys.stdout.write("%s\n" % libraries[ii])
-            
+
     openmm_include_path = os.getenv('OPENMM_INCLUDE_PATH')
     if not openmm_include_path:
         reportError("Set OPENMM_INCLUDE_PATH to point to the include directory for OpenMM")
@@ -198,8 +196,8 @@ def buildKeywordDictionary(major_version_num=MAJOR_VERSION_NUM,
         extra_compile_args.append('/EHsc')
     else:
         if platform.system() == 'Darwin':
-            extra_compile_args += ['-stdlib=libc++', '-mmacosx-version-min=10.7']                                                                                                                                       
-            extra_link_args += ['-stdlib=libc++', '-mmacosx-version-min=10.7', '-Wl', '-rpath', openmm_lib_path]                                                                                                          
+            extra_compile_args += ['-stdlib=libc++', '-mmacosx-version-min=10.7']
+            extra_link_args += ['-stdlib=libc++', '-mmacosx-version-min=10.7', '-Wl', '-rpath', openmm_lib_path]
 
     library_dirs=[openmm_lib_path]
     include_dirs=openmm_include_path.split(';')
@@ -222,11 +220,11 @@ def buildKeywordDictionary(major_version_num=MAJOR_VERSION_NUM,
     for key in sorted(iter(setupKeywords)):
          value         = setupKeywords[key]
          outputString += key.rjust(firstTab) + str( value ).rjust(secondTab) + "\n"
-    
+
     sys.stdout.write("%s" % outputString)
 
     return setupKeywords
-    
+
 
 def main():
     if sys.version_info < (2, 6):

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

 #!/usr/bin/env python
 #
 #
- 
+
 """Build swig imput file from xml encoded header files (see gccxml)."""
 __author__ = "Randall J. Radmer"
 __version__ = "1.0"
-  
- 
+
+
 import sys, os
 import time
 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 = "   ";
 
@@ -83,7 +121,7 @@ def getClassMethodList(classNode, skipMethods):
     shortClassName=stripOpenmmPrefix(className)
     methodList=[]
     for section in findNodes(classNode, "sectiondef", kind="public-static-func")+findNodes(classNode, "sectiondef", kind="public-func"):
-        for memberNode in findNodes(section, "memberdef", kind="function", prot="public"):    
+        for memberNode in findNodes(section, "memberdef", kind="function", prot="public"):
             methDefinition = getText("definition", memberNode)
             shortMethDefinition=stripOpenmmPrefix(methDefinition)
             methName=shortMethDefinition.split()[-1]
@@ -95,14 +133,14 @@ def getClassMethodList(classNode, skipMethods):
                     sys.stderr.write("Warning: Including class %s\n" %
                                      shortClassName)
                     continue
-    
+
             if (shortClassName, methName) in skipMethods: continue
-    
+
             # set template info
-    
+
             templateType = getText("templateparamlist/param/type", memberNode)
             templateName = getText("templateparamlist/param/declname", memberNode)
-    
+
             methodList.append( (shortClassName,
                                 memberNode,
                                 shortMethDefinition,
@@ -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: