documentation cleanup

Author: Richard Jones

TODO.txt

@@ -1,7 +1,10 @@
 This file has been re-purposed to contain specifically the items that need
 doing before the next release:
 
+- sessions, otks and indexing in RDBMSes
 - add tests for group-by-multilink so I finally implement it for the RDBMSes
 - full coverage analysis for unit tests
-- migrate to numeric ID values (fixes bug 817217)
+- s/getnode/getitem in backends (and s/Node/Item)
+- activity_by meta-property
 
+- migrate to numeric ID values (fixes bug 817217)

doc/.cvsignore

@@ -11,7 +11,7 @@ features.html
 upgrading.html
 glossary.html
 design.html
-maintenance.html
+admin_guide.html
 overview.html
 mysql.html
 postgresql.html

doc/admin_guide.txt

@@ -2,7 +2,7 @@
 Administration Guide
 ====================
 
-:Version: $Revision: 1.1 $
+:Version: $Revision: 1.2 $
 
 .. contents::
 
@@ -23,7 +23,7 @@ There's two "installations" that we talk about when using Roundup:
    Support files
      <python dir>\share\roundup\...
 
-   and on *nix (eg. Linux):
+   and on Unix-like systems (eg. Linux):
 
    Scripts
      <python root>/bin/...
@@ -84,7 +84,7 @@ Maintenance of Roundup can involve one of the following:
 1. `tracker backup`_ 
 2. `software upgrade`_
 3. `migrating backends`_
-3. `moving a tracker`_
+4. `moving a tracker`_
 
 
 Tracker Backup

roundup/__init__.py

@@ -15,9 +15,9 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: __init__.py,v 1.26 2004-01-20 00:05:07 richard Exp $
+# $Id: __init__.py,v 1.27 2004-02-11 23:55:08 richard Exp $
 
-''' Roundup - issue tracking for knowledge workers.
+'''Roundup - issue tracking for knowledge workers.
 
 This is a simple-to-use and -install issue-tracking system with
 command-line, web and e-mail interfaces.
@@ -43,11 +43,11 @@
  |                             Storage Layer                               |
   -------------------------------------------------------------------------
 
-The first layer represents the users (chocolate).
-The second layer is the Roundup interface to the users (vanilla).
-The third and fourth layers are the internal Roundup database storage
-  mechanisms (strawberry).
-The final, lowest layer is the underlying database storage (rum).
+1. The first layer represents the users (chocolate).
+2. The second layer is the Roundup interface to the users (vanilla).
+3. The third and fourth layers are the internal Roundup database storage
+   mechanisms (strawberry).
+4. The final, lowest layer is the underlying database storage (rum).
 
 These are implemented in the code in the following manner::
 
@@ -66,6 +66,7 @@
 written by Ka-Ping Yee in the "doc" directory. If nothing else, it has a
 much prettier cake :)
 '''
+__docformat__ = 'restructuredtext'
 
 __version__ = '0.7.0b1'
 

roundup/admin.py

@@ -16,10 +16,11 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: admin.py,v 1.61 2003-11-13 04:12:10 richard Exp $
+# $Id: admin.py,v 1.62 2004-02-11 23:55:08 richard Exp $
 
 '''Administration commands for maintaining Roundup trackers.
 '''
+__docformat__ = 'restructuredtext'
 
 import sys, os, getpass, getopt, re, UserDict, shutil, rfc822
 from roundup import date, hyperdb, roundupdb, init, password, token, rcsv
@@ -826,6 +827,7 @@ def do_table(self, args):
         specified, all properties are displayed. By default, the column widths
         are the width of the largest value. The width may be explicitly defined
         by defining the property as "name:width". For example::
+
           roundup> table priority id,name:10
           Id Name
           1  fatal-bug 
@@ -834,7 +836,8 @@ def do_table(self, args):
           4  feature   
 
         Also to make the width of the column the width of the label,
-        leave a trailing : without a width on the property. E.G.
+        leave a trailing : without a width on the property. For example::
+
           roundup> table priority id,name:
           Id Name
           1  fata

roundup/backends/__init__.py

@@ -15,13 +15,14 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: __init__.py,v 1.25 2003-10-25 22:53:26 richard Exp $
+# $Id: __init__.py,v 1.26 2004-02-11 23:55:08 richard Exp $
 
-''' Container for the hyperdb storage backend implementations.
+'''Container for the hyperdb storage backend implementations.
 
 The __all__ variable is constructed containing only the backends which are
 available.
 '''
+__docformat__ = 'restructuredtext'
 
 __all__ = []
 

roundup/backends/back_anydbm.py

@@ -15,13 +15,13 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-#$Id: back_anydbm.py,v 1.134 2003-12-10 01:40:51 richard Exp $
-'''
-This module defines a backend that saves the hyperdatabase in a database
-chosen by anydbm. It is guaranteed to always be available in python
+#$Id: back_anydbm.py,v 1.135 2004-02-11 23:55:08 richard Exp $
+'''This module defines a backend that saves the hyperdatabase in a
+database chosen by anydbm. It is guaranteed to always be available in python
 versions >2.1.1 (the dumbdbm fallback in 2.1.1 and earlier has several
 serious bugs, and is not available)
 '''
+__docformat__ = 'restructuredtext'
 
 try:
     import anydbm, sys
@@ -50,10 +50,10 @@ class Database(FileStorage, hyperdb.Database, roundupdb.Database):
     '''A database for storing records containing flexible data types.
 
     Transaction stuff TODO:
-        . check the timestamp of the class file and nuke the cache if it's
-          modified. Do some sort of conflict checking on the dirty stuff.
-        . perhaps detect write collisions (related to above)?
-
+    
+    - check the timestamp of the class file and nuke the cache if it's
+      modified. Do some sort of conflict checking on the dirty stuff.
+    - perhaps detect write collisions (related to above)?
     '''
     def __init__(self, config, journaltag=None):
         '''Open a hyperdatabase given a specifier to some storage.
@@ -92,14 +92,15 @@ def __init__(self, config, journaltag=None):
         self.lockfile.flush()
 
     def post_init(self):
-        ''' Called once the schema initialisation has finished.
+        '''Called once the schema initialisation has finished.
         '''
         # reindex the db if necessary
         if self.indexer.should_reindex():
             self.reindex()
 
     def refresh_database(self):
-        "Rebuild the database"
+        """Rebuild the database
+        """
         self.reindex()
 
     def reindex(self):
@@ -1366,8 +1367,11 @@ def destroy(self, nodeid):
         WARNING: this method should never be used except in extremely rare
                  situations where there could never be links to the node being
                  deleted
+
         WARNING: use retire() instead
+
         WARNING: the properties of this node will not be available ever again
+
         WARNING: really, use retire() instead
 
         Well, I think that's enough warnings. This method exists mostly to
@@ -1418,14 +1422,15 @@ def getkey(self):
         return self.key
 
     def labelprop(self, default_to_id=0):
-        ''' Return the property name for a label for the given node.
+        '''Return the property name for a label for the given node.
 
         This method attempts to generate a consistent label for the node.
         It tries the following in order:
-            1. key property
-            2. "name" property
-            3. "title" property
-            4. first property from the sorted property name list
+
+        1. key property
+        2. "name" property
+        3. "title" property
+        4. first property from the sorted property name list
         '''
         k = self.getkey()
         if  k:
@@ -1597,21 +1602,23 @@ def getnodeids(self, db=None):
 
     def filter(self, search_matches, filterspec, sort=(None,None),
             group=(None,None), num_re = re.compile('^\d+$')):
-        ''' Return a list of the ids of the active nodes in this class that
-            match the 'filter' spec, sorted by the group spec and then the
-            sort spec.
-
-            "filterspec" is {propname: value(s)}
-            "sort" and "group" are (dir, prop) where dir is '+', '-' or None
-                               and prop is a prop name or None
-            "search_matches" is {nodeid: marker}
-
-            The filter must match all properties specificed - but if the
-            property value to match is a list, any one of the values in the
-            list may match for that property to match. Unless the property
-            is a Multilink, in which case the item's property list must
-            match the filterspec list.
-        '''
+        """Return a list of the ids of the active nodes in this class that
+        match the 'filter' spec, sorted by the group spec and then the
+        sort spec.
+
+        "filterspec" is {propname: value(s)}
+
+        "sort" and "group" are (dir, prop) where dir is '+', '-' or None
+        and prop is a prop name or None
+
+        "search_matches" is {nodeid: marker}
+
+        The filter must match all properties specificed - but if the
+        property value to match is a list, any one of the values in the
+        list may match for that property to match. Unless the property
+        is a Multilink, in which case the item's property list must
+        match the filterspec list.
+        """
         cn = self.classname
 
         # optimise filterspec

roundup/backends/back_bsddb.py

@@ -15,10 +15,10 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-#$Id: back_bsddb.py,v 1.28 2003-11-14 00:11:18 richard Exp $
-'''
-This module defines a backend that saves the hyperdatabase in BSDDB.
+#$Id: back_bsddb.py,v 1.29 2004-02-11 23:55:08 richard Exp $
+'''This module defines a backend that saves the hyperdatabase in BSDDB.
 '''
+__docformat__ = 'restructuredtext'
 
 import bsddb, os, marshal
 from roundup import hyperdb, date

roundup/backends/back_bsddb3.py

@@ -15,10 +15,10 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-#$Id: back_bsddb3.py,v 1.21 2003-11-14 00:11:18 richard Exp $
-'''
-This module defines a backend that saves the hyperdatabase in BSDDB3.
+#$Id: back_bsddb3.py,v 1.22 2004-02-11 23:55:08 richard Exp $
+'''This module defines a backend that saves the hyperdatabase in BSDDB3.
 '''
+__docformat__ = 'restructuredtext'
 
 import bsddb3, os, marshal
 from roundup import hyperdb, date