diff options
| -rw-r--r-- | doc/conf.py | 5 | ||||
| -rw-r--r-- | doc/ids.txt | 53 | ||||
| -rw-r--r-- | doc/index.txt | 2 | ||||
| -rw-r--r-- | doc/libbe.bug.txt | 7 | ||||
| -rw-r--r-- | doc/libbe.txt | 12 | ||||
| -rw-r--r-- | libbe/bug.py | 12 |
6 files changed, 84 insertions, 7 deletions
diff --git a/doc/conf.py b/doc/conf.py index b2dab25..ea03b08 100644 --- 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 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 f1c1542..9c964fa 100644 --- 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 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 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 0b40921..a4b569f 100644 --- 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' |