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 :).

1 files changed, 75 insertions, 0 deletions

diff --git a/doc/hacking.txt b/doc/hacking.txt
new file mode 100644
index 0000000..5b075f9
--- /dev/null
+++ b/doc/hacking.txt
@@ -0,0 +1,75 @@
+**********
+Hacking BE
+**********
+
+Adding commands
+===============
+
+To write a plugin, you simply create a new file in the
+``libbe/commands/`` directory.  Take a look at one of the simpler
+plugins (e.g. ``remove.py``) for an example of how that looks, and to
+start getting a feel for the libbe interface.
+
+See ``libbe/commands/base.py`` for the definition of the important
+classes ``Option``, ``Argument``, ``Command``, ``InputOutput``,
+``StorageCallbacks``, and ``UserInterface`` classes.  You'll be
+subclassing ``Command`` for your command, but all those classes will
+be important.
+
+
+Command completion
+------------------
+
+BE implements a general framework to make it easy to support command
+completion for arbitrary plugins.  In order to support this system,
+any of your completable ``Argument()`` instances (in your command's
+``.options`` or ``.args``) should be initialized with some valid
+completion_callback function.  Some common cases are defined in
+``libbe.command.util``.  If you need more flexibility, see
+``libbe.command.list``'s ``--sort`` option for an example of
+extensions via ``libbe.command.util.Completer``, or write a custom
+completion function from scratch.
+
+
+Adding user interfaces
+======================
+
+Take a look at ``libbe/ui/command_line.py`` for an example.  Basically
+you'll need to setup a ``UserInterface`` instance for running commands.
+More details to come after I write an HTML UI...
+
+
+Testing
+=======
+
+Run any tests in your module with::
+
+    be$ python test.py <python.module.name>
+
+for example:
+
+    be$ python test.py libbe.command.merge
+
+For a definition of "any tests", see ``test.py``'s
+``add_module_tests()`` function.
+
+Note that you will need to run ``make`` before testing a clean BE
+branch to auto-generate required files like ``libbe/_version.py``.
+
+
+Profiling
+=========
+
+Find out which 20 calls take the most cumulative time (time of
+execution + childrens' times)::
+
+    $ python -m cProfile -o profile be [command] [args]
+    $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"
+
+It's often useful to toss::
+
+    import sys, traceback
+    print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:])
+
+into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if
+you're not sure why they're being called.