Merged Eric Kow's HTML escaping patch

Merged initial Sphinx documentation structure.

There's still a long way to go in this direction, but the basic
framework is now in place.  Toss in numpydoc-style docstrings
  http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
when you have time, and things will gradually improve over time.

I also punted our user ID creation/parsing in libbe.ui.util.user to
the email module.  This way IDs are handled in an RFC-compliant way
(less suprising for users) and by someone else (less work for us :).

Consolidated Makefile and doc/man/module.mk.  Incorperated doc/Makefile.

Now
  make sphinx
builds the Sphinx HTML documentation (in doc/.build/html), and
  make clean
cleans up everything.

Having a separate module.mk was just making things confusing, so I
took it out ;).

Fixed docstrings so only Sphinx errors are "autosummary" and "missing attribute"

Use email.utils.formataddr/parseaddr to generate/parse user IDs

Use numpydoc and generate-libbe-txt.py to autogenerate API documentation

Added bugdir and comment modules to Sphinx docs

Added libbe.bug to the Sphinx documentation

Broke out install.txt + reStructuredText markup fixes

Added page titles to the documentation & adjusted section levels.

Sphynx now gets version string automatically.

Moved manpage source doc/src to doc/man

Created Sphinx framework with sphinx-quickstart and added .txt extensiosns

Avoid double-escaping in 'be html'.

Use ${HOME}/.local as default prefix.
This is apparently a new standard.

Sort comments in `be html`.

Fix be-xml-to-mbox handling of non-text/* content types

Restore "content_type" kwarg to Comment.new_reply().

It had been removed in
    revno: 473.1.43
    committer: W. Trevor King <wking@drexel.edu>
    branch nick: be.restructure
    timestamp: Mon 2009-12-14 07:37:51 -0500
    message:
      Transitioned comment to Command format
when we pushed unicode encoding/decoding back to the Storage backend.

However, with the addition of libbe.util.id.short_to_long_text(),
we need it again.

Also add a Doctest showing a non-text/* comment, so utilities dealing
with them can see what they'll be working with.

Made Bzr/Darcs.version_cmp() more robust in response to Chris' email.

From: Chris Ball <cjb@laptop.org>
Subject: Test suite status

...
I ran the wking@drexel.edu-20100130162439-pmh5tg6kuq92x3l5 testsuite
on Fedora 13/Rawhide.  Had to downgrade Mercurial (bzr-hg doesn't
support 1.4.2 yet) and bzr (my Fedora package contained a "b4" in the
version string, which breaks libbe/storage/vcs/bzr.py:version_cmp()).
...

Fixed Chris' "zero name length for Mercurial w/o ~/.hgrc" bug.

From: Chris Ball <cjb@laptop.org>
Subject: Test suite status
Date: Mon, 01 Feb 2010 11:27:53 -0500
Message-id: <m38wbcor92.fsf@pullcord.laptop.org>

...

I hit the "assert len(name) > 0" in libbe/ui/util/libbe.py, coming from
hg.py when running with no ~/.hgrc.  Fixed by the following patch:

=== modified file 'libbe/storage/vcs/hg.py'
--- libbe/storage/vcs/hg.py     2010-01-21 17:45:49 +0000
+++ libbe/storage/vcs/hg.py     2010-02-01 16:17:03 +0000
@@ -87,7 +87,14 @@
         return tmp_stdout.getvalue().rstrip('\n')

     def _vcs_get_user_id(self):
-        return self._u_invoke_client('showconfig', 'ui.username')
+        output = self._u_invoke_client('showconfig', 'ui.username')
+        if output != "":
+            return output.rstrip('\n')
+        else:
+            # guess missing info
+            name = libbe.ui.util.user.get_fallback_username()
+            email = libbe.ui.util.user.get_fallback_email()
+            return libbe.ui.util.user.create_user_id(name, email)

     def _vcs_detect(self, path):
         """Detect whether a directory is revision-controlled using Mercurial"""

Fix command name output of `be --complete`.

By adding command_names option to libbe.command.commands.  Previous
versions of `be --complete` printed "import_xml", not "import-xml".

Also fixed libbe.command.base's doctests, so test.py can run them.

Clearer UnicodeDecodeError message in command_line.dispatch().

See #bea/e30# ("Where should the vcs-name and encoding configuration
options live?")  for details.

libbe.command.html.HTMLGen._long_to_linked_user() handles failed conversion.

Before, anything matching libbe.util.id.REGEXP was convert-or-die.
Now it's convert-or-no-op.  Much safer ;).  The new
_long_to_linked_user doctest would have failed with the old
implementation.

Always load settings when initializing BugDir from storage.

Avoids problems like:

$ be html
Traceback (most recent call last):
  File "be", line 21, in <module>
    sys.exit(libbe.ui.command_line.main())
  File ".../libbe/ui/command_line.py", line 327, in main
    ret = dispatch(ui, command, args)
  File ".../libbe/ui/command_line.py", line 267, in dispatch
    ret = ui.run(command, options, args)
  File ".../libbe/command/base.py", line 504, in run
    return command.run(options, args)
  File ".../libbe/command/base.py", line 233, in run
    self.status = self._run(**params)
  File ".../libbe/command/html.py", line 111, in _run
    html_gen.run(params['output'])
  File ".../libbe/command/html.py", line 154, in run
    bugs.sort()
  File ".../libbe/bug.py", line 261, in __cmp__
    return cmp_full(self, other)
  File ".../libbe/bug.py", line 818, in __call__
    val = comparison(bug_1, bug_2)
  File ".../libbe/bug.py", line 750, in cmp_status
    return cmp(status_index[bug_1.status], status_index[bug_2.status])
  File ".../libbe/storage/util/properties.py", line 223,
in _fget
    raise ValueCheckError(name, value, value_allowed_fn)
libbe.storage.util.properties.ValueCheckError: open-feature not allowed by <function <lambda> at 0x84b610c> for status

Fix `be show` handling for no IDs

Add version information to test.py stderr for easier error reproduction

Fix editor spawning on null-string EDITOR and VISUAL.

  $ EDITOR= VISUAL= python -c 'import os; import sys; print os.environ'
  {..., 'EDITOR': '', ..., 'VISUAL': '', ...}

Merged some new bugs and be-xml-to-mbox extra_strings fix

Added #bea/169# : Generating per-bugdir/bug/comment change logs

Removed taglines other cruft from #bea/d99# comments

Fix "extra_strings" -> "extra-strings" typos in be-xml-to-mbox

Add some workarounds for older bzrlibs.  Tested on 1.3.1

Work around "bzr ls --non-recursive PATH : no list" bug in old bzrlib.

See: https://bugs.launchpad.net/bzr/+bug/158690

Bug affected versions:
  0.90.0 (reported)
  1.3.1  (my test suite hit it)
Doesn't affect versions:
  2.0+   (non_recursive -> recursive)
But I haven't isolated the source more specifically.

Working around it for everything < 2.0 should be safe, but the cutoff
could be fine-tuned if someone wants to dig through the bzr.dev
history...

Fix bzrlib.builtins.cmd_cat() output for pre 1.6.0 bzrlibs.

Fixed in bzr.dev
  revno: 3341.2.1
  revision-id: bialix@ukr.net-20080407074826-5lwuyv4dn1qlijg4
  parent: pqm@pqm.ubuntu.com-20080407044456-s1a9orh0kssphdh9
  committer: Alexander Belchenko <bialix@ukr.net>
  branch nick: cmd-cat
  timestamp: Mon 2008-04-07 10:48:26 +0300
  message: `bzr cat` no more internally used Tree.print_file().
Merged into bzr.dev's trunk
  revno: 3512 [merge]
  revision-id: pqm@pqm.ubuntu.com-20080626004245-dnw85so4xqg8r9hy
  parent: pqm@pqm.ubuntu.com-20080625230724-lyux37pu8nx8tq34
  parent: aaron@aaronbentley.com-20080626001706-wo3w74fwgliy12s4
  committer: Canonical.com Patch Queue Manager <pqm@pqm.ubuntu.com>
  branch nick: +trunk
  timestamp: Thu 2008-06-26 01:42:45 +0100
  message: (bialix) Deprectate (Branch|Repository).print_file, fix cmd_cat

Before bzr branch 1.6
  bzr.dev$ bzr tags
  ...
  bzr-1.5rc1           3418.6.3
  bzr-1.6              3606.5.9
  ...

Fixes:

python test.py -q libbe.storage.vcs.bzr
...............................FSome value:1E..
======================================================================
ERROR: Get should be able to return the previous version.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/wking/src/fun/be/be.wtk/libbe/storage/base.py", line 976, in test_
get_previous_version
    ret = self.s.get(self.id, revision=revs[i])
  File "/home/wking/src/fun/be/be.wtk/libbe/storage/base.py", line 335, in get
    value = self._get(*args, **kwargs)
  File "/home/wking/src/fun/be/be.wtk/libbe/storage/vcs/base.py", line 849, in _
get
    raise InvalidID(id, revision)
InvalidID: unlikely id in revision 1
...

Fix bzrlib.builtins.cmd_ls() recursion argument for pre 2.0 bzrlibs.

$ python test.py libbe.storage.vcs.bzr
...
======================================================================
ERROR: Children list should be revision dependent.
----------------------------------------------------------------------
Traceback (most recent call last):
  File ".../libbe/storage/base.py", line 997, in test_
get_previous_children
    ret = sorted(self.s.children('parent', revision=revs[i]))
  File ".../libbe/storage/base.py", line 314, in child
ren
    return self._children(*args, **kwargs)
  File ".../libbe/storage/vcs/base.py", line 811, in _
children
    path = self.path(id, revision, relpath=False)
  File ".../libbe/storage/vcs/base.py", line 716, in p
ath
    path = self._vcs_path(id, revision)
  File ".../libbe/storage/vcs/bzr.py", line 145, in _v
cs_path
    self.repo, revision=revision, recursive=True)
  File ".../libbe/storage/vcs/bzr.py", line 163, in _v
cs_listdir
    cmd.run(revision=revision, path=path, recursive=recursive)
  File "/usr/lib/python2.5/site-packages/bzrlib/commands.py", line 800, in ignor
e_pipe
    result = func(*args, **kwargs)
TypeError: run() got an unexpected keyword argument 'recursive'
...

The change is due to (in bzr.dev):

revno: 4206.2.1
revision-id: ian.clatworthy@canonical.com-20090326133831-orvicmmc6w29mpfp
parent: pqm@pqm.ubuntu.com-20090326063330-evutyvml3067dpsz
committer: Ian Clatworthy <ian.clatworthy@canonical.com>
branch nick: bzr.ls-recursive-off
timestamp: Thu 2009-03-26 23:38:31 +1000
message: ls should be non-recursive by default

Which occured between bzr-1.9rc1 and 2.0rc1.:

bzr.dev$ bzr tags
2.0rc1               4634.9.1
...
bzr-1.9rc1           3815.3.1
bzr-2.0.1            4634.73.2
...

Merged with be.wtk trunk

Oops, fix Comment doctest EDITOR cleanup

Add #bea/9c2# : Can comment punt functionality to email.Message?

Don't accidentally spawn VISUAL in Comment doctests.

Implement Arch._vcs_path()

Fixes VersionedStorage_commit_TestCase.test_get_previous_children.
Should have fixed
  VersionedStorage_commit_TestCase.test_get_previous_version
too, but 'tla file-find' is buggy:
  https://bugs.launchpad.net/ubuntu/+source/tla/+bug/513472

Also:
  * sort children in test_get_previous_children, since we shouldn't
    require a particular child order
  * unescape filenames in Arch._diff()
  * remove debugging prints from Arch._parse_diff()
  * remove silly blank line in git.py I'd stumbled across ;).

Implement Arch._vcs_changed().

Fixes VersionedStorage_changed_TestCase.test_changed failure.

Fix StorageTestCase.classname -> ._classname()

Introduced in
  wking@drexel.edu-20100127152727-nu58o4g6jea5or7w

`be html` links (<a href="...) #-delimited references in text/* bodies.

Merged clarifications requested by Ben Finney

Make VCS error messages and Storage test failures more descriptive

Merged be.auth, adding "--auth" to `be serve`

Add --help, --quiet options to test.py.

Fixes Ben's "unintuitive test.py interface" bug:

Date: Wed, 27 Jan 2010 14:09:14 +1100
From: Ben Finney
Subject: [Be-devel] Re: Test suite on Trevor's development branch
...
> $ python ./test.py -q
>
> ----------------------------------------------------------------------
> Ran 0 tests in 0.000s
>
> OK

Running a Python unittest-capable test suite with "-q" should run it in
"quiet" mode, where progress is indicated by single characters along a
lone, and only failures and errors are reported.
...

Encourage a run of `make` to build auto-generated files.

Fixes Ben's "unintuitive test procedure" bug:

Date: Wed, 27 Jan 2010 14:09:14 +1100
From: Ben Finney
Subject: [Be-devel] Re: Test suite on Trevor's development branch
...
> $ python ./test.py
> Traceback (most recent call last):
[...]
> ImportError: No module named _version

So it's not possible to simply get a copy of the branch and try running
the test suite.
...

Streamlined libbe.command.serve, adding --auth option, #/bea/c1b#, and testing.

Added --ssl to `be serve` using cherrypy.wsgiserver.

Convert libbe.command.serve to WSGI for increased flexibility.

The Python Web Server Gateway Interface (WSGI) is a simple and
universal interface between web servers and web applications or
frameworks.  See PEP 333 for details.
  http://www.python.org/dev/peps/pep-0333/

Rework fix for #bea/8fc# : be crashes on outdated id-cache

Now we re-run CachedPathID.init in an 'append' mode, rather than
starting over from scratch.  This avoids problems like

  ======================================================================
  ERROR: Should not be able to add children to non-directories.
  ----------------------------------------------------------------------
  Traceback (most recent call last):
    File ".../be.wtk/libbe/storage/base.py", line 680, in test_add_invalid_directory
      self.s.add('child', 'parent', directory=False)
    File ".../be.wtk/libbe/storage/base.py", line 248, in add
      self._add(id, *args, **kwargs)
    File ".../be.wtk/libbe/storage/vcs/base.py", line 737, in _add
      path = self._cached_path_id.add_id(id, parent)
    File ".../be.wtk/libbe/storage/vcs/base.py", line 267, in add_id
      parent_path = self.path(parent, relpath=True)
    File ".../be.wtk/libbe/storage/vcs/base.py", line 246, in path
      raise InvalidID(uuid)
  InvalidID: parent in revision None

and similar.

Don't print 'Multiple paths' message on cache regen

Fixed #bea/8fc# : be crashes on outdated id-cache

Also explicitly avoid loading or saving settings for root comments.

Added bug #bea/8fc# : be crashes on outdated id-cache

Merged be.doc documentation rewrite + bugfixes + new bugs

Highlights:
  * Fix broken Diff.comment_body_change_string implementation.
  * Fix List --severity handling, added --important
  * Fix `be target --help`
  * Fix non-text/plain `be comment` code and added 'Created
    comment...' output

Rewrote documentation

Added some bugs (and fixed typo) noticed while rewriting documentation

Fix Diff.comment_body_change_string's difflib.unified_diff call

Fixed List --severity handling, added --important

Fix vars call for `be target --help`

Update --subscriber option help string for Subscribe

Modern ID format in `be list` _long_help

Fix broken handling of non-text/plain comments

Added "Created comment..." output to `be comment`

Reorganized documentation to clean doc/ for user-readable files

Fixed some bugs in settings_object handling and got test_usage.sh working.

Highlights:
  * clarified settings_object handling and improved unittests
  * added `be list --mine`
  * fixed some bugs in List, Import_XML, Init
  * added Storage.exists() (haven't implemented it in all VCS backends though).
  * added VCS.path()

Update test_usage.sh

Fix typos in untested parts of List and Import_XML for test_usage.py

Added `be list --mine`

Init should tell the UI about its connected storage and bugdir.

Move BugDir, Bug, and Comment to new _setup_saved_settings

Added testSimplePropertySetStorageSave and relavant rewrites to settings_object

It hadn't been handling the "attach storage after initializing"
technique that BugDir, Bug, and Comment use when from_memory==True.
Now it does, by refusing to overwrite self.settings with the
newly-loaded settings.

Add Bzr._vcs_exists() anyway :p

We don't need VCS._vcs_exists yet, with exists only used in _add

Minor cleanups + remove debuging line in Init doctest

Add VCS._exists(), VCS.path().  Fix default handling in VCS._get().

VCS.path() consolidates a bunch of distributed code.

The VCS backend cannot distinguish between _EMPTY and '' entry values,
so it assumes
  len(contents) == 0
means _EMPTY.  However, it had been returing None then, not default
like its supposed to.

Added _EMPTY and Storage.exists() to libbe.storage.base.

There seem to be problems distinguishing between "added but unset" IDs
and "added and set to ''" IDs.  Now _EMPTY lets us mark "added but unset",
and Storage.exists() handles "already added?" more clearly than the old
hack "does .get() succeed?".

Reworked settings_object module, but command.init tests still fail:

$ python test.py libbe.command.init
Doctest: libbe.command.init.Init ... FAIL
...
-----------------------
File ".../libbe/command/init.py", line 47, in libbe.command.init.Init
Failed example:
    ui.run(cmd)
Exception raised:
    Traceback (most recent call last):
      ...
      File "/tmp/be.wtk/libbe/command/init.py", line 97, in _run
        bd = libbe.bugdir.BugDir(storage, from_storage=False)
      File "/tmp/be.wtk/libbe/bugdir.py", line 185, in __init__
        self.save()
      File "/tmp/be.wtk/libbe/bugdir.py", line 228, in save
        self.save_settings()
      File "/tmp/be.wtk/libbe/bugdir.py", line 204, in save_settings
        mf = mapfile.generate(self._get_saved_settings())
      File "/tmp/be.wtk/libbe/storage/util/settings_object.py", line 230, in _get_saved_settings
        self, self._setting_name_to_attr_name(k))
      File "/tmp/be.wtk/libbe/storage/util/properties.py", line 194, in _fget
        value = fget(self)
      File "/tmp/be.wtk/libbe/storage/util/properties.py", line 329, in _fget
        primer(self)
      File "/tmp/be.wtk/libbe/storage/util/settings_object.py", line 69, in prop_load_settings
        self.load_settings()
      File "/tmp/be.wtk/libbe/bugdir.py", line 194, in load_settings
        self.settings = mapfile.parse(settings_mapfile)
      File "/tmp/be.wtk/libbe/storage/util/mapfile.py", line 123, in parse
        c = yaml.load(contents)
      ...
      File "/usr/lib/python2.6/site-packages/yaml/reader.py", line 213, in update_raw
        data = self.stream.read(size)
    AttributeError: 'NoneType' object has no attribute 'read'
...

Added unprimableVal option to primed_property.

For clearer handling of the "Tried to load but failed" case.

Added tests to Init to check for empty settings file

Bugfix merge: better Comment.xml() & libbe.util.id.parse_user()

Highlights:
  * new Comment.safe_in_reply_to to improve comment xml output.
  * don't raise MultipleIDMatches if one of the matches is exact.

Add Comment.safe_in_reply_to to improve comment xml output.

Now
  be show --xml ID | be-xml-to-mbox | catmutt
shows appropriate linking regardless of missing references or
references to alt-ids in the original comments.  On the other hand,
  be show --xml ID | be import-xml
could alter alt-ids.  If that's a problem we could turn off
save_in_reply_to usage via an option to the xml methods in the future.

Don't raise MultipleIDMatches if one of the matches is exact.

Merge assorted bugfixes and optimizations.

Highlights:
  * `be new` adds creator field like its supposed to (oops :p).
  * `be list --xml` uses <be-xml> format (was <bugs>).
  * `be import-xml` handles root comments appropriately.
  * `be` raises an appropriate help message.
  * `be help` works.
  * `be html` prints Comment.id.user() information.
  * better SavedSettingsObject._get_saved_settings() avoids data loss.
  * be-mbox-to-xml -> be-mail-to-xml and adds assorted format support.
  * be-xml-to-mbox and be-handle-mail work with new libbe layout.
  * BugDir.uuids() now caches on-disk uuids for speed.
  * Mercurial detection works for mercurial <= 1.1.2 _and_ >= 1.2
  * Fix bugs in VCS._children() relative/absolute path handling.

Fix be-handle-mail's notification creation for new libbe structure

Ajdust Target tests for cached BugDir.uuids() implementation

Fix _uuids_cache reset in BugDir._clear_bugs

Update libbe.storage.util.settings_object tests for new ._get_saved_settings

Fix version import for mercurial <= 1.1.2

Use _get_user_id() in New, remove unused 'user-id' prop. from Commit.

Added creator field to bugs without creator information.  Mostly this
is due to the recent lack of creator-setting in `be new`.

Add _uuids_cache management to BugDir._clear_bugs

Add wrap_id to improve id handling in be-xml-to-mbox

Converted `be list --xml` to <be-xml> format.

Fixed up be-xml-to-mbox following the recent libbe restructuring.

Moved stdout manipulation in be-mail-to-xml into the if __name__ ==
'__main__' block, in case some other module wants to recycle some of
its functions/methods.

Fix not-yet-loaded bug in SavedSettingsObject._get_saved_settings()

The earlier implementation only copied in the currently loaded
properties and the required ones.  The new implementation copies
in _all_ the non-default properties.

Improve `be import-xml` handling of root comments + tests.

Fix BugDir._uuid_cache management for new_bug()/remove_bug().

Initial implementation in wking@drexel.edu-20100120192451-j206hn1s78u9a3ys
missed them.

Strip footers (signatures) in be-mail-to-xml

'be-mbox-to-xml' -> 'be-mail-to-xml' + support for several formats.

Optimized BugDir.uuids, caching on-disk bug uuids.

Output of
  python -m cProfile -o profile be list
  python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats()"
on my slow netbook before optimization:
   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
    10290    0.417    0.000   10.832    0.001 libbe/bugdir.py:237(uuids)
after optimization:
      105    0.063    0.001    0.250    0.002 libbe/bugdir.py:237(uuids)
The old generator produced many more calls than the new
implementation, but the number of calls was not the source of the
slowdown (data not shown ;).