Experiment with auto-documentation

github/GenerateDocumentation.py

@@ -0,0 +1,14 @@
+#!/bin/env python
+
+import GithubObject
+import GithubObjects
+
+def generateDocumentation():
+    classes = [ getattr( GithubObjects, c ) for c in dir( GithubObjects ) if hasattr( getattr( GithubObjects, c ), "_autoDocument" ) ]
+    doc = ""
+    for c in classes:
+        doc += c._autoDocument()
+    return doc
+
+if __name__ == "__main__":
+    print generateDocumentation()

github/GithubObject.py

@@ -47,9 +47,11 @@ def GithubObject( className, *attributePolicies ):
     class GithubObject:
         __attributeDefinitions = dict()
         __methodDefinitions = dict()
+        __attributePolicies = list()
 
         @staticmethod
         def _addAttributePolicy( attributePolicy ):
+            GithubObject.__attributePolicies.append( attributePolicy )
             attributePolicy.apply( GithubObject )
 
         @staticmethod
@@ -103,6 +105,15 @@ def GithubObject( className, *attributePolicies ):
             attributeDefinition = GithubObject.__attributeDefinitions[ attributeName ]
             attributeDefinition.updateAttributes( self )
 
+        @classmethod
+        def _autoDocument( cls ):
+            doc = "Class `" + cls.__name__ + "`\n"
+            doc += "=" * ( len( cls.__name__ ) + 8 ) + "\n"
+            for attributePolicy in cls.__attributePolicies:
+                doc += attributePolicy.autoDocument()
+            doc += "\n"
+            return doc
+
     GithubObject.__name__ = className
     GithubObject._addAttributePolicy( SeveralAttributePolicies( attributePolicies ) )
 

github/ObjectCapacities/ArgumentsChecker.py

@@ -19,3 +19,18 @@ class ArgumentsChecker:
             if argumentName not in data:
                 raise TypeError()
         return data
+
+    def documentParameters( self ):
+        mandatory = ", ".join( self.__mandatoryParameters )
+        optional = "[" + ", ".join( self.__optionalParameters ) + "]"
+
+        if len( self.__mandatoryParameters ) == 0:
+            if len( self.__optionalParameters ) == 0:
+                return ""
+            else:
+                return " " + optional + " "
+        else:
+            if len( self.__optionalParameters ) == 0:
+                return " " + mandatory + " "
+            else:
+                return " " + mandatory + ", " + optional + " "

github/ObjectCapacities/Basic.py

@@ -20,6 +20,9 @@ class AttributeFromCallable:
     def apply( self, cls ):
         cls._addAttribute( self.__name, AttributeFromCallable.AttributeDefinition( self.__name, self.__callable ) )
 
+    def autoDocument( self ):
+        return "* `" + self.__name + "`\n"
+
 ### @todo include the ArgumentsChecker
 class MethodFromCallable:
     def __init__( self, name, callable ):
@@ -29,6 +32,9 @@ class MethodFromCallable:
     def apply( self, cls ):
         cls._addMethod( self.__name, self.__callable )
 
+    def autoDocument( self ):
+        return "* `" + self.__name + "( ... )`\n"
+
 class InternalAttribute:
     class AttributeDefinition:
         def __init__( self, typePolicy ):
@@ -55,6 +61,9 @@ class InternalAttribute:
     def apply( self, cls ):
         cls._addAttribute( self.__attributeName, InternalAttribute.AttributeDefinition( self.__typePolicy ) )
 
+    def autoDocument( self ):
+        return "* `" + self.__attributeName + "`: `" + self.__typePolicy.documentTypeName() + "`\n"
+
 class ExternalAttribute:
     def __init__( self, attributeName, typePolicy ):
         self.__attributeName = attributeName
@@ -69,6 +78,9 @@ class ExternalAttribute:
             obj._github._dataRequest( "GET", obj._baseUrl + "/" + self.__attributeName, None, None )
         )
 
+    def autoDocument( self ):
+        return "* `get_" + self.__attributeName + "()`: `" + self.__typePolicy.documentTypeName() + "`\n"
+
 class SeveralAttributePolicies:
     def __init__( self, attributePolicies ):
         self.__attributePolicies = attributePolicies
@@ -76,3 +88,6 @@ class SeveralAttributePolicies:
     def apply( self, cls ):
         for attributePolicy in self.__attributePolicies:
             attributePolicy.apply( cls )
+
+    def autoDocument( self ):
+        return "".join( attributePolicy.autoDocument() for attributePolicy in self.__attributePolicies )

github/ObjectCapacities/List.py

@@ -24,6 +24,9 @@ class ElementAddable( ListCapacity ):
             None
         )
 
+    def autoDocument( self ):
+        return "* `add_to_" + self.safeAttributeName + "( " + self.singularName + " )`\n    * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class ElementRemovable( ListCapacity ):
     def apply( self, cls ):
         cls._addMethod( "remove_from_" + self.safeAttributeName, self.__execute )
@@ -36,6 +39,9 @@ class ElementRemovable( ListCapacity ):
             None
         )
 
+    def autoDocument( self ):
+        return "* `remove_from_" + self.safeAttributeName + "( " + self.singularName + " )`\n    * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class ElementHasable( ListCapacity ):
     def apply( self, cls ):
         cls._addMethod( "has_in_" + self.safeAttributeName, self.__execute )
@@ -48,6 +54,9 @@ class ElementHasable( ListCapacity ):
             None
         ) == 204
 
+    def autoDocument( self ):
+        return "* `has_in_" + self.safeAttributeName + "( " + self.singularName + " )`: `bool`\n    * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class ElementCreatable( ListCapacity ):
     def __init__( self, mandatoryParameters, optionalParameters, attributeModifiers = {} ):
         self.__argumentsChecker = ArgumentsChecker( mandatoryParameters, optionalParameters )
@@ -75,6 +84,9 @@ class ElementCreatable( ListCapacity ):
             attributes[ attributeName ] = attributeModifier( obj )
         return attributes
 
+    def autoDocument( self ):
+        return "* `create_" + self.singularName + "(" + self.__argumentsChecker.documentParameters() + ")`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class ElementGetable( ListCapacity ):
     def __init__( self, mandatoryParameters, optionalParameters, attributeModifiers = {} ):
         self.__argumentsChecker = ArgumentsChecker( mandatoryParameters, optionalParameters )
@@ -97,6 +109,9 @@ class ElementGetable( ListCapacity ):
             attributes[ attributeName ] = attributeModifier( obj )
         return attributes
 
+    def autoDocument( self ):
+        return "* `get_" + self.singularName + "( ... )`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class SeveralElementsAddable( ListCapacity ):
     def apply( self, cls ):
         cls._addMethod( "add_to_" + self.safeAttributeName, self.__execute )
@@ -112,6 +127,9 @@ class SeveralElementsAddable( ListCapacity ):
             ]
         )
 
+    def autoDocument( self ):
+        return "* `add_to_" + self.safeAttributeName + "( " + self.singularName + ", .... )`\n    * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class SeveralElementsRemovable( ListCapacity ):
     def apply( self, cls ):
         cls._addMethod( "remove_from_" + self.safeAttributeName, self.__execute )
@@ -127,6 +145,9 @@ class SeveralElementsRemovable( ListCapacity ):
             ]
         )
 
+    def autoDocument( self ):
+        return "* `remove_from_" + self.safeAttributeName + "( " + self.singularName + ", .... )`\n    * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
+
 class ListGetable( ListCapacity ):
     def __init__( self, mandatoryParameters, optionalParameters, attributeModifiers = {} ):
         self.__argumentsChecker = ArgumentsChecker( mandatoryParameters, optionalParameters )
@@ -150,6 +171,9 @@ class ListGetable( ListCapacity ):
             )
         ]
 
+    def autoDocument( self ):
+        return "* `get_" + self.safeAttributeName + "()`: list of `" + self.typePolicy.documentTypeName() + "`\n"
+
     def __modifyAttributes( self, obj, attributes ):
         for attributeName, attributeModifier in self.__attributeModifiers.iteritems():
             attributes[ attributeName ] = attributeModifier( obj )
@@ -170,6 +194,9 @@ class ListSetable( ListCapacity ):
             ]
         )
 
+    def autoDocument( self ):
+        return "* `set_" + self.safeAttributeName + "( " + self.singularName + ", .... )`\n"
+
 class ListDeletable( ListCapacity ):
     def apply( self, cls ):
         cls._addMethod( "delete_" + self.safeAttributeName, self.__execute )
@@ -182,6 +209,9 @@ class ListDeletable( ListCapacity ):
             None
         )
 
+    def autoDocument( self ):
+        return "* `delete_" + self.safeAttributeName + "()`\n"
+
 def ExternalListOfObjects( attributeName, singularName, type, *capacities ):
     for capacity in capacities:
         capacity.setList( attributeName, singularName, ObjectTypePolicy( type ) )

github/ObjectCapacities/TypePolicies.py

@@ -5,6 +5,10 @@ class SimpleTypePolicy:
     def getIdentity( self, value ):
         return value
 
+    def documentTypeName( self ):
+        ### @todo
+        return "SHIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIT"
+
 class ObjectTypePolicy:
     def __init__( self, type ):
         self.__type = type
@@ -21,3 +25,6 @@ class ObjectTypePolicy:
     def getIdentity( self, obj ):
         assert isinstance( obj, self.__type )
         return obj._identity
+
+    def documentTypeName( self ):
+        return self.__type.__name__