Added libbe.bug to the Sphinx documentation

diff --git a/doc/conf.py b/doc/conf.py
index b2dab25ecb80bd2f0030a773f2b3199f7f8668b9..ea03b08a377e035e2606c525b34c35022b487ee0 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -13,12 +13,13 @@
 
 import sys, os
 
-import libbe.version
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.append(os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
+
+import libbe.version
 
 # -- General configuration -----------------------------------------------------
 

diff --git a/doc/ids.txt b/doc/ids.txt
new file mode 100644 (file)
index 0000000..ba1837b
--- /dev/null
+++ b/doc/ids.txt
@@ -0,0 +1,53 @@
+**********
+Object IDs
+**********
+
+Format
+======
+
+BE IDs are formatted::
+
+    <bug-directory>[/<bug>[/<comment>]]
+
+where each ``<..>`` is a UUID.  For example::
+
+    bea86499-824e-4e77-b085-2d581fa9ccab/3438b72c-6244-4f1d-8722-8c8d41484e35
+
+refers to bug ``3438b72c-6244-4f1d-8722-8c8d41484e35`` which is
+located in bug directory ``bea86499-824e-4e77-b085-2d581fa9ccab``.
+This is a bit of a mouthful, so you can truncate each UUID so long as
+it remains unique.  For example::
+
+    bea/343
+
+If there were two bugs ``3438...`` and ``343a...`` in ``bea``, you'd
+have to use::
+
+    bea/3438
+
+BE will only truncate each UUID down to three characters to slightly
+future-proof the short user ids.  However, if you want to save keystrokes
+and you *know* there is only one bug directory, feel free to truncate
+all the way to zero characters::
+
+    /3438
+
+Cross references
+================
+
+To refer to other bug-directories/bugs/comments from bug comments, simply
+enclose the ID in pound signs (``#``).  BE will automatically expand the
+truncations to the full UUIDs before storing the comment, and the reference
+will be appropriately truncated (and hyperlinked, if possible) when the
+comment is displayed.
+
+Scope
+=====
+
+Although bug and comment IDs always appear in compound references,
+UUIDs at each level are globally unique.  For example, comment
+``bea/343/ba96f1c0-ba48-4df8-aaf0-4e3a3144fc46`` will *only* appear
+under ``bea/343``.  The prefix (``bea/343``) allows BE to reduce
+caching global comment-lookup tables and enables easy error messages
+("I couldn't find ``bea/343/ba9`` because I don't know where the
+``bea`` bug directory is located").

diff --git a/doc/index.txt b/doc/index.txt
index f1c1542cf5a3ef0c72f792be4662c34f7cc2521e..9c964fac56bdc2f6fff3dd847523c53fec2aa50a 100644 (file)
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -29,7 +29,7 @@ Contents:
    distributed_bugtracking.txt
    hacking.txt
    spam.txt
-
+   libbe.txt
 
 Indices and tables
 ==================

diff --git a/doc/libbe.bug.txt b/doc/libbe.bug.txt
new file mode 100644 (file)
index 0000000..41427c5
--- /dev/null
+++ b/doc/libbe.bug.txt
@@ -0,0 +1,7 @@
+****************
+:mod:`libbe.bug`
+****************
+
+.. automodule:: libbe.bug
+   :members:
+   :undoc-members:

diff --git a/doc/libbe.txt b/doc/libbe.txt
new file mode 100644 (file)
index 0000000..dd04df1
--- /dev/null
+++ b/doc/libbe.txt
@@ -0,0 +1,12 @@
+************
+:mod:`libbe`
+************
+
+.. automodule:: libbe
+   :members:
+   :undoc-members:
+
+.. toctree::
+   :maxdepth: 2
+
+   libbe.bug.txt

diff --git a/libbe/bug.py b/libbe/bug.py
index 0b40921befaf6c08c63164669f435fc2514f7fe6..a4b569fd742bdde5a84fc87e0bf59dbd18c959dd 100644 (file)
--- a/libbe/bug.py
+++ b/libbe/bug.py
@@ -16,8 +16,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""
-Define the Bug class for representing bugs.
+"""Define the Bug class for representing bugs.
 """
 
 import copy
@@ -122,7 +121,9 @@ load_status(active_status_def, inactive_status_def)
 
 
 class Bug (settings_object.SavedSettingsObject):
-    """
+    """A bug (or issue) is a place to store attributes and attach
+    comments.  In mailing-list terms, a bug is analogous to a thread.
+
     >>> b = Bug()
     >>> print b.status
     open
@@ -132,6 +133,7 @@ class Bug (settings_object.SavedSettingsObject):
     There are two formats for time, int and string.  Setting either
     one will adjust the other appropriately.  The string form is the
     one stored in the bug's settings file on disk.
+
     >>> print type(b.time)
     <type 'int'>
     >>> print type(b.time_string)
@@ -333,7 +335,7 @@ class Bug (settings_object.SavedSettingsObject):
         return istring + sep.join(lines).rstrip('\n')
 
     def from_xml(self, xml_string, verbose=True):
-        """
+        u"""
         Note: If a bug uuid is given, set .alt_id to it's value.
         >>> bugA = Bug(uuid="0123", summary="Need to test Bug.from_xml()")
         >>> bugA.date = "Thu, 01 Jan 1970 00:00:00 +0000"
@@ -410,6 +412,7 @@ class Bug (settings_object.SavedSettingsObject):
         Add a comment too the current bug, under the parent specified
         by comment.in_reply_to.
         Note: If a bug uuid is given, set .alt_id to it's value.
+
         >>> bugA = Bug(uuid='0123', summary='Need to test Bug.add_comment()')
         >>> bugA.creator = 'Jack'
         >>> commA = bugA.comment_root.new_reply(body='comment A')
@@ -506,6 +509,7 @@ class Bug (settings_object.SavedSettingsObject):
         """
         Merge info from other into this bug.  Overrides any attributes
         in self that are listed in other.explicit_attrs.
+
         >>> bugA = Bug(uuid='0123', summary='Need to test Bug.merge()')
         >>> bugA.date = 'Thu, 01 Jan 1970 00:00:00 +0000'
         >>> bugA.creator = 'Frank'