Merge pull request #79 from dpgrote/add_documented_metaclass

Added metaclass to manipulate the class doc strings

Author: ax3l

PICMI_Python/README.md

@@ -19,6 +19,9 @@ should take the inputs and convert them to the appropriate inputs for the specif
 **Warning:**
 The standard is still evolving at this point. The most basic components of the standard have been defined and are being refined. New components are being added.
 
+The documentation of the classes is in the numpydoc format - see https://numpydoc.readthedocs.io.
+The classes are setup so that the doc strings of the implementation classes will have the picmistandard
+doc string prepended, followed by any implementation specific doc string.
 
 # For developers
 

PICMI_Python/base.py

@@ -32,7 +32,29 @@ def register_constants(implementation_constants):
 def _get_constants():
     return _implementation_constants
 
-class _ClassWithInit(object):
+
+class _DocumentedMetaClass(type):
+    """This is used as a metaclass that combines the __doc__ of the picmistandard base and of the implementation"""
+    def __new__(cls, name, bases, attrs):
+        # "if bases" skips this for the _ClassWithInit (which has no bases)
+        # "if bases[0].__doc__ is not None" skips this for the picmistandard classes since their bases[0] (i.e. _ClassWithInit)
+        # has no __doc__.
+        if bases and bases[0].__doc__ is not None:
+            implementation_doc = attrs.get('__doc__', '')
+            if implementation_doc:
+                # The format of the added string is intentional.
+                # The double return "\n\n" is needed to start a new section in the documentation.
+                # Then the four spaces matches the standard level of indentation for doc strings
+                # (assuming PEP8 formatting).
+                # The final return "\n" assumes that the implementation doc string begins with a return,
+                # i.e. a line with only three quotes, """.
+                attrs['__doc__'] = bases[0].__doc__ + """\n\n    Implementation specific documentation\n""" + implementation_doc
+            else:
+                attrs['__doc__'] = bases[0].__doc__
+        return super(_DocumentedMetaClass, cls).__new__(cls, name, bases, attrs)
+
+
+class _ClassWithInit(metaclass=_DocumentedMetaClass):
     def handle_init(self, kw):
         # --- Grab all keywords for the current code.
         # --- Arguments for other supported codes are ignored.