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, 23 insertions, 17 deletions

diff --git a/libbe/storage/vcs/arch.py b/libbe/storage/vcs/arch.py
index 38b1d02..3a50414 100644
--- a/libbe/storage/vcs/arch.py
+++ b/libbe/storage/vcs/arch.py
@@ -18,8 +18,9 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""
-GNU Arch (tla) backend.
+"""GNU Arch_ (tla) backend.
+
+.. _Arch: http://www.gnu.org/software/gnu-arch/
 """
 
 import codecs
@@ -56,6 +57,8 @@ def new():
     return Arch()
 
 class Arch(base.VCS):
+    """:class:`base.VCS` implementation for GNU Arch.
+    """
     name = 'arch'
     client = client
     _archive_name = None
@@ -90,10 +93,10 @@ class Arch(base.VCS):
         self._add_project_code(path)
 
     def _create_archive(self, path):
-        """
-        Create a temporary Arch archive in the directory PATH.  This
-        archive will be removed by
-          destroy->_vcs_destroy->_remove_archive
+        """Create a temporary Arch archive in the directory PATH.  This
+        archive will be removed by::
+
+            destroy->_vcs_destroy->_remove_archive
         """
         # http://regexps.srparish.net/tutorial-tla/new-archive.html#Creating_a_New_Archive
         assert self._archive_name == None
@@ -109,8 +112,7 @@ class Arch(base.VCS):
                               self._archive_dir, cwd=path)
 
     def _invoke_client(self, *args, **kwargs):
-        """
-        Invoke the client on our archive.
+        """Invoke the client on our archive.
         """
         assert self._archive_name != None
         command = args[0]
@@ -164,16 +166,20 @@ class Arch(base.VCS):
         return '%s/%s' % (self._archive_name, self._project_name)
 
     def _adjust_naming_conventions(self, path):
-        """
-        By default, Arch restricts source code filenames to
-          ^[_=a-zA-Z0-9].*$
-        See
-          http://regexps.srparish.net/tutorial-tla/naming-conventions.html
-        Since our bug directory '.be' doesn't satisfy these conventions,
-        we need to adjust them.
+        """Adjust `Arch naming conventions`_ so ``.be`` is considered source
+        code.
+
+        By default, Arch restricts source code filenames to::
+
+            ^[_=a-zA-Z0-9].*$
 
-        The conventions are specified in
-          project-root/{arch}/=tagging-method
+        Since our bug directory ``.be`` doesn't satisfy these conventions,
+        we need to adjust them.  The conventions are specified in::
+
+            project-root/{arch}/=tagging-method
+
+        .. _Arch naming conventions:
+          http://regexps.srparish.net/tutorial-tla/naming-conventions.html
         """
         tagpath = os.path.join(path, '{arch}', '=tagging-method')
         lines_out = []