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, 52 insertions, 0 deletions

diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py
new file mode 100644
index 0000000..35eb5c4
--- /dev/null
+++ b/doc/generate-libbe-txt.py
@@ -0,0 +1,52 @@
+#!/usr/bin/python
+#
+# Copyright
+
+"""Auto-generate reStructuredText of the libbe module tree for Sphinx.
+"""
+
+import sys
+import os, os.path
+
+sys.path.insert(0, os.path.abspath('..'))
+from test import python_tree
+
+def title(modname):
+    t = ':mod:`%s`' % modname
+    delim = '*'*len(t)
+    return '\n'.join([delim, t, delim, '', ''])
+
+def automodule(modname):
+    return '\n'.join([
+            '.. automodule:: %s' % modname,
+            '   :members:',
+            '   :undoc-members:',
+            '', ''])
+
+def toctree(children):
+    if len(children) == 0:
+        return ''
+    return '\n'.join([
+            '.. toctree::',
+            '   :maxdepth: 2',
+            '',
+            ] + [
+            '   %s.txt' % c for c in sorted(children)
+            ] + ['', ''])
+
+def make_module_txt(modname, children):
+    filename = os.path.join('libbe', '%s.txt' % modname)
+    if not os.path.exists('libbe'):
+        os.mkdir('libbe')
+    if os.path.exists(filename):
+        return None # don't overwrite potentially hand-written files.
+    f = file(filename, 'w')
+    f.write(title(modname))
+    f.write(automodule(modname))
+    f.write(toctree(children))
+    f.close()
+
+if __name__ == '__main__':
+    pt = python_tree(root_path='../libbe', root_modname='libbe')
+    for node in pt.traverse():
+        make_module_txt(node.modname, [c.modname for c in node])