docs updates

biweeklybudget/backfill_ofx.py

@@ -57,6 +57,9 @@
 
 
 class OfxBackfiller(object):
+    """
+    Class to backfill OFX in database from files on disk.
+    """
 
     def __init__(self, savedir):
         logger.info('Initializing OfxBackfiller with savedir=%s', savedir)
@@ -68,6 +71,9 @@ def __init__(self, savedir):
         logger.debug('Database initialized')
 
     def run(self):
+        """
+        Main entry point - run the backfill.
+        """
         logger.debug('Checking for Accounts with statement directories')
         for acct in db_session.query(Account).all():
             p = os.path.join(settings.STATEMENTS_SAVE_PATH, acct.name)
@@ -151,6 +157,9 @@ def _do_one_file(self, updater, path):
 
 
 def parse_args():
+    """
+    Parse command-line arguments.
+    """
     p = argparse.ArgumentParser(description='Backfill OFX from disk')
     p.add_argument('-v', '--verbose', dest='verbose', action='count', default=0,
                    help='verbose output. specify twice for debug-level output.')
@@ -159,6 +168,9 @@ def parse_args():
 
 
 def main():
+    """
+    Main entry point - instantiate and run :py:class:`~.OfxBackfiller`.
+    """
     global logger
     format = "[%(asctime)s %(levelname)s] %(message)s"
     logging.basicConfig(level=logging.WARNING, format=format)

biweeklybudget/cliutils.py

@@ -39,13 +39,18 @@
 
 
 def set_log_info(logger):
-    """set logger level to INFO"""
+    """
+    set logger level to INFO via :py:func:`~.set_log_level_format`.
+    """
     set_log_level_format(logger, logging.INFO,
                          '%(asctime)s %(levelname)s:%(name)s:%(message)s')
 
 
 def set_log_debug(logger):
-    """set logger level to DEBUG, and debug-level output format"""
+    """
+    set logger level to DEBUG, and debug-level output format,
+    via :py:func:`~.set_log_level_format`.
+    """
     set_log_level_format(
         logger,
         logging.DEBUG,

biweeklybudget/db.py

@@ -70,9 +70,13 @@
 if settings.DB_CONNSTRING.startswith('mysql'):
     engine_args['connect_args'] = {'sql_mode': 'TRADITIONAL'}
 
+#: The database engine object; return value of
+#: :py:func:`sqlalchemy.create_engine`.
 engine = create_engine(settings.DB_CONNSTRING, **engine_args)
 
 logger.debug('Creating DB session')
+
+#: :py:class:`sqlalchemy.orm.scoping.scoped_session` session
 db_session = scoped_session(
     sessionmaker(autocommit=False, autoflush=False, bind=engine)
 )
@@ -84,6 +88,10 @@
 
 
 def init_db():
+    """
+    Initialize the database; call
+    :py:meth:`sqlalchemy.schema.MetaData.create_all` on the metadata object.
+    """
     # import all modules here that might define models so that
     # they will be registered properly on the metadata.  Otherwise
     # you will have to import them first before calling init_db()
@@ -115,10 +123,10 @@ def upsert_record(model_class, key_fields, **kwargs):
     committed. If not, a new one will be inserted. Either way, the record is
     returned.
 
-    ``db_session.commit()`` is NOT called.
+    :py:meth:`sqlalchemy.orm.session.Session.commit` is **NOT** called.
 
     :param model_class: the class of model to insert/update
-    :type model_class: ``biweeklybudget.models.base.Base``
+    :type model_class: biweeklybudget.models.base.ModelAsDict
     :param key_fields: The field name(s) (keys in ``kwargs``) that make up the
       primary key. This can be a single string, or a list or tuple of strings
       for compound keys. The values for these key fields MUST be included in