add initial docs

edbob/commands.py

@@ -184,6 +184,26 @@ class Subcommand(edbob.Object):
             )
         self.add_parser_args(self.parser)
 
+    @property
+    @requires_impl(is_property=True)
+    def name(self):
+        """
+        The name of the subcommand.
+
+        .. note::
+           The subcommand name should ideally be limited to 12 characters in
+           order to preserve formatting consistency when displaying help text.
+        """
+        pass
+
+    @property
+    @requires_impl(is_property=True)
+    def description(self):
+        """
+        The description for the subcommand.
+        """
+        pass
+
     def __repr__(self):
         return "<Subcommand: %s>" % self.name
 
@@ -196,28 +216,6 @@ class Subcommand(edbob.Object):
         """
         pass
             
-    @property
-    @requires_impl(is_property=True)
-    def description(self):
-        """
-        The description for the subcommand.  This must be provided within your
-        subclass, as a simple class attribute.
-        """
-        pass
-
-    @property
-    @requires_impl(is_property=True)
-    def name(self):
-        """
-        The name of the subcommand.  This must be provided within your
-        subclass, as a simple class attribute.
-
-        .. note::
-           The subcommand name should ideally be limited to 12 characters in
-           order to preserve formatting consistency when displaying help text.
-        """
-        pass
-
     def _run(self, *args):
         args = self.parser.parse_args(list(args))
         return self.run(args)

edbob/modules.py

@@ -26,7 +26,6 @@
 ``edbob.modules`` -- Module Tools
 """
 
-
 import sys
 
 from edbob import exceptions
@@ -83,7 +82,6 @@ def load_spec(spec):
     necessary.
     """
 
-    
     module_path, obj = spec.split(':')
     module = import_module_path(module_path)
     try:

edbob/pyramid/scaffolds/edbob/+package+/commands.py_tmpl

@@ -39,7 +39,7 @@ class InitDatabaseCommand(commands.Subcommand):
     description = "Initialize the database"
 
     def run(self, args):
-        from edbob.db import engine, Session
+        from edbob.db import engine
         from edbob.db.util import install_core_schema
         from edbob.db.exceptions import CoreSchemaAlreadyInstalled
 
@@ -50,6 +50,9 @@ class InitDatabaseCommand(commands.Subcommand):
             print err
             return
 
+        # Activate any extensions you like here...
+
+        from edbob.db import Session
         from edbob.db.classes import Role, User
         from edbob.db.auth import administrator_role
 

edbob/sqlalchemy.py

@@ -50,11 +50,11 @@ def getset_factory(collection_class, proxy):
 
 def table_with_uuid(name, metadata, *args, **kwargs):
     """
+    .. highlight:: python
+
     Convenience function to abstract the addition of the ``uuid`` column to a
     new table.  Can be used to replace this::
 
-       .. highlight:: python
-
        Table(
            'things', metadata,
            Column('uuid', String(32), primary_key=True, default=get_uuid),

edbob/time.py

@@ -85,14 +85,14 @@ def set_timezone(tz):
     Sets edbob's notion of the "local" timezone.  ``tz`` should be an Olson
     name.
 
+    .. highlight:: ini
+
     You usually don't need to call this yourself, since it's called by
     :func:`edbob.init()` whenever the config file includes a timezone (but
     only as long as ``edbob.time`` is configured to be initialized)::
 
-       .. highlight:: ini
-
        [edbob]
-       init = ['edbob.time']
+       init = edbob.time
 
        [edbob.time]
        timezone = US/Central

edbob/util.py

@@ -52,4 +52,8 @@ class requires_impl(edbob.Object):
             msg += " (within the %s module)" % self.__class__.__module__
             raise NotImplementedError(msg)
 
+        # wrapped.__doc__ = func.__doc__ + "\n\n    This must be implemented by the derived class."
+        wrapped.__doc__ = """%s
+
+        This must be implemented by the derived class.""" % func.__doc__
         return wrapped