aboutsummaryrefslogtreecommitdiffstats
path: root/doc/README.dev
diff options
context:
space:
mode:
authorW. Trevor King <wking@drexel.edu>2010-01-24 11:20:47 -0500
committerW. Trevor King <wking@drexel.edu>2010-01-24 11:20:47 -0500
commit53074356bf715c820d3b9b852cd45e5073ba765d (patch)
treea921fe2c28dce45718ee32018b23bf0e3bea7222 /doc/README.dev
parent9244610e37ed846bf3789601b0ef4645b4f98409 (diff)
downloadbugseverywhere-53074356bf715c820d3b9b852cd45e5073ba765d.tar.gz
Rewrote documentation
Diffstat (limited to 'doc/README.dev')
-rw-r--r--doc/README.dev69
1 files changed, 38 insertions, 31 deletions
diff --git a/doc/README.dev b/doc/README.dev
index a2b8d30..cfb1896 100644
--- a/doc/README.dev
+++ b/doc/README.dev
@@ -4,61 +4,68 @@ Extending 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.
+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.
+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 commands
-.options or .args) should be initialized with some valid
+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.
+``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...
+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
+Run any tests in your module with::
-For a definition of "any tests", see test.py's add_module_tests()
-function.
+ 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.
Profiling
=========
Find out which 20 calls take the most cumulative time (time of
-execution + childrens' times).
+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::
- $ python -m cProfile -o profile be [command] [args]
- $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"
+ import sys, traceback
+ print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:])
-It's often useful to toss a
- 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.
+into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if
+you're not sure why they're being called.