test: convert to Python 3 compatibility

[be.git] / README

diff --git a/README b/README
index fe0fd08238fda1fd019304dc719946f633df303e..3c7ab8f10f7f1f3aeb4810c3e7a706b99f9afb9b 100644 (file)
--- a/README
+++ b/README
@@ -1,21 +1,47 @@
 Bugs Everywhere
 ===============
-This is Bugs Everywhere, a bugtracker built on distributed revision
-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
-all.
+
+This is Bugs Everywhere (BE), a bugtracker built on distributed version
+control.  It works with Arch, Bazaar, Darcs, Git, Mercurial, and Monotone
+at the 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
+==========
+
+BE is available as a Git repository::
+
+    $ git clone git://gitorious.org/be/be.git be
+
+See the homepage_ for details.  If you do branch the Git repo, you'll
+need to run::
+
+    $ make
+
+to build some auto-generated files (e.g. ``libbe/_version.py``), and::
+
+    $ make install
+
+to install BE.  By default BE will install into your home directory,
+but you can tweak the ``PREFIX`` variable in ``Makefile`` to install
+to another location.
+
+.. _homepage: http://bugseverywhere.org/
+
+
 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
@@ -23,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.
+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
+.. _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:
+  https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt