aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorW. Trevor King <wking@drexel.edu>2010-02-08 17:05:12 -0500
committerW. Trevor King <wking@drexel.edu>2010-02-08 17:05:12 -0500
commit37d61e9ecd8768b25ba4aff3c657ccc56f086dd0 (patch)
tree31214efb9536a319473277610534cf2f37215ed1 /README
parent3f27c5c3bbc1ecd00db51c4894a9bf9651ae4fbb (diff)
parent960565a8cc80f98d0a8bfa77029fbc78692ea1a1 (diff)
downloadbugseverywhere-37d61e9ecd8768b25ba4aff3c657ccc56f086dd0.tar.gz
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 :).
Diffstat (limited to 'README')
-rw-r--r--README37
1 files changed, 22 insertions, 15 deletions
diff --git a/README b/README
index b39fca1..ef597bb 100644
--- a/README
+++ b/README
@@ -1,15 +1,16 @@
Bugs Everywhere
===============
-This is Bugs Everywhere (BE), a bugtracker built on distributed revision
+This is Bugs Everywhere (BE), a bugtracker built on distributed version
control. It works with Arch, Bazaar, Darcs, Git, and Mercurial at the
-moment, but is easily extensible. It can also function with no RCS at
+moment, but is easily extensible. It can also function with no VCS at
all.
The idea is to package the bug information with the source code, so that
bugs can be marked "fixed" in the branches that fix them. So, instead of
numbers, bugs have globally unique ids.
+
Getting BE
==========
@@ -38,8 +39,9 @@ Getting started
To get started, you must set the bugtracker root. Typically, you will want to
set the bug root to your project root, so that Bugs Everywhere works in any
-part of your project tree.
-$ be init -r $PROJECT_ROOT
+part of your project tree.::
+
+ $ be init -r $PROJECT_ROOT
To create bugs, use ``be new $DESCRIPTION``. To comment on bugs, you
can can use ``be comment $BUG_ID``. To close a bug, use
@@ -47,18 +49,23 @@ can can use ``be comment $BUG_ID``. To close a bug, use
commands, see ``be help``. You can also look at the usage examples in
``test_usage.sh``.
+
Documentation
=============
-If ``be help`` isn't scratching your itch, there's also
-
-* doc/tutorial (a gentle introduction to BE)
-* doc/distributed_bugtracking (notes on distributed workflows)
-* doc/spam (notes on removing spam entries from VCSs)
-* doc/README.dev (a guide to hacking BE)
-
-The documentation is marked up in reStructuredText_, so you can use
-the docutils_ to convert it to other formats if you desire.
-
-.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+If ``be help`` isn't scratching your itch, the full documentation is
+available in the doc directory as reStructuredText_ . You can build
+the full documentation with Sphinx_ , convert single files with
+docutils_ , or browse through the doc directory by hand.
+doc/index.txt is a good place to start. If you do use Sphinx, you'll
+need to install numpydoc_ for automatically generating API
+documentation. See the ``NumPy/SciPy documentation guide``_ for an
+introduction to the syntax.
+
+.. _reStructuredText:
+ http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _Sphinx: http://sphinx.pocoo.org/
.. _docutils: http://docutils.sourceforge.net/
+.. _numpydoc: http://pypi.python.org/pypi/numpydoc
+.. _NumPy/SciPy documentation guide:
+ http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines