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

2 files changed, 178 insertions, 0 deletions

diff --git a/doc/man/be.1.sgml b/doc/man/be.1.sgml
new file mode 100644
index 0000000..a2df21f
--- /dev/null
+++ b/doc/man/be.1.sgml
@@ -0,0 +1,134 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+<!-- Process this file with docbook-to-man to generate an nroff manual
+     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
+     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
+     less'.  A typical entry in a Makefile or Makefile.am is:
+
+be.1: be.1.sgml
+	docbook-to-man $< > $@
+
+	The docbook-to-man binary is found in the docbook-to-man package.
+	Please remember that if you create the nroff version in one of the
+	debian/rules file targets (such as build), you will need to include
+	docbook-to-man in your Build-Depends control field.
+
+  -->
+
+  <!ENTITY dhfirstname "<firstname>Ben</firstname>">
+  <!ENTITY dhsurname   "<surname>Finney</surname>">
+  <!-- Please adjust the date whenever revising the manpage. -->
+  <!ENTITY dhdate      "<date>2009-06-25</date>">
+  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
+       allowed: see man(7), man(1). -->
+  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
+  <!ENTITY dhemail     "<email>ben+debian@benfinney.id.au</email>">
+  <!ENTITY dhusername  "Ben Finney">
+  <!ENTITY dhucpackage "<refentrytitle>BUGS-EVERYWHERE</refentrytitle>">
+  <!ENTITY dhpackage   "bugs-everywhere">
+  <!ENTITY pkgfullname "Bugs Everywhere">
+  <!ENTITY uccmdname   "<refentrytitle>BE</refentrytitle>">
+  <!ENTITY cmdname     "be">
+
+  <!ENTITY debian      "<productname>Debian</productname>">
+  <!ENTITY gnu         "<acronym>GNU</acronym>">
+  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
+]>
+
+<refentry>
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+    <copyright>
+      <year>2009</year>
+      <holder>&dhusername;</holder>
+    </copyright>
+    &dhdate;
+  </refentryinfo>
+  <refmeta>
+    &uccmdname;
+
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>&cmdname;</refname>
+
+    <refpurpose>distributed bug tracker</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>&cmdname;</command>
+      <arg><replaceable>command</replaceable></arg>
+      <arg><replaceable>command_options ...</replaceable></arg>
+      <arg><replaceable>command_args ...</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>&cmdname; help</command>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>&cmdname; help</command>
+      <arg><replaceable>command</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+
+    <para>This manual page documents briefly the
+      <command>&cmdname;</command> command, part of the
+      &pkgfullname; package.</para>
+
+    <para><command>&cmdname;</command> allows commandline interaction
+      with the &pkgfullname; database in a project tree.</para>
+
+  </refsect1>
+  <refsect1>
+    <title>COMMANDS</title>
+    <variablelist>
+      <varlistentry>
+        <term><command>help</command>
+        </term>
+        <listitem>
+          <para>Print help for be and a list of all available commands.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+
+    <para>This manual page was written by &dhusername; <&dhemail;> for
+      the &debian; system (but may be used by others). Permission is
+      granted to copy, distribute and/or modify this document under
+      the terms of the &gnu; General Public License, Version 2 or any
+      later version published by the Free Software Foundation.
+    </para>
+	<para>
+	  On Debian systems, the complete text of the GNU General Public
+	  License can be found in /usr/share/common-licenses/GPL.
+	</para>
+
+  </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/man/module.mk b/doc/man/module.mk
new file mode 100644
index 0000000..ea4eacc
--- /dev/null
+++ b/doc/man/module.mk
@@ -0,0 +1,44 @@
+# :vim: filetype=make : -*- makefile; coding: utf-8; -*-
+
+# doc/module.mk
+# Part of Bugs Everywhere, a distributed bug tracking system.
+#
+# Copyright (C) 2008-2010 Chris Ball <cjb@laptop.org>
+#                         Gianluca Montecchi <gian@grys.it>
+#                         W. Trevor King <wking@drexel.edu>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+# Makefile module for documentation
+
+MODULE_DIR := doc/src
+
+MANPAGES = be.1
+manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES})
+
+GENERATED_FILES += ${manpage_files}
+
+
+.PHONY: doc
+doc: man
+
+build: doc
+
+
+.PHONY: man
+man: ${manpage_files}
+
+%.1: %.1.sgml
+	docbook-to-man $< > $@