diff options
| -rw-r--r-- | README | 11 | ||||
| -rw-r--r-- | doc/conf.py | 3 | ||||
| -rw-r--r-- | doc/doc.txt | 23 | ||||
| -rw-r--r-- | doc/generate-libbe-txt.py | 52 | ||||
| -rw-r--r-- | doc/index.txt | 9 | ||||
| -rw-r--r-- | doc/libbe.bug.txt | 7 | ||||
| -rw-r--r-- | doc/libbe.bugdir.txt | 7 | ||||
| -rw-r--r-- | doc/libbe.comment.txt | 7 | ||||
| -rw-r--r-- | doc/libbe.txt | 14 | ||||
| -rw-r--r-- | libbe/bug.py | 4 | ||||
| -rw-r--r-- | libbe/bugdir.py | 2 | ||||
| -rw-r--r-- | libbe/command/assign.py | 2 | ||||
| -rw-r--r-- | libbe/command/serve.py | 3 | ||||
| -rw-r--r-- | libbe/comment.py | 2 |
14 files changed, 96 insertions, 50 deletions
@@ -57,8 +57,15 @@ 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. +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: + http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines diff --git a/doc/conf.py b/doc/conf.py index ea03b08..1090a28 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,8 @@ import libbe.version # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', + 'numpydoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] diff --git a/doc/doc.txt b/doc/doc.txt new file mode 100644 index 0000000..e1b7a3a --- /dev/null +++ b/doc/doc.txt @@ -0,0 +1,23 @@ +**************************** +Producing this documentation +**************************** + +This documentation is written in reStructuredText_, and produced +using Sphinx_ and the numpydoc_ extension. The documentation source +should be fairly readable without processing, but you can compile the +documentation, you'll need to install Sphinx and numpydoc:: + + $ easy_install Sphinx + $ easy_install numpydoc + +.. _Sphinx: http://sphinx.pocoo.org/ +.. _numpydoc: http://pypi.python.org/pypi/numpydoc + +See the reStructuredText quick reference and the `NumPy/SciPy +documentation guide`_ for an introduction to the documentation +syntax. + +.. _reStructuredText: + http://docutils.sourceforge.net/docs/user/rst/quickref.html +.. _NumPy/SciPy documentation guide: + http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py new file mode 100644 index 0000000..ec874fa --- /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 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]) diff --git a/doc/index.txt b/doc/index.txt index 9c964fa..6765a68 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -2,9 +2,9 @@ Welcome to the bugs-everywhere documentation! ============================================= Bugs Everywhere (BE) is 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 VCS at all. +control. It works with Arch_, Bazaar_, Darcs_, Git_, and Mercurial_ +at the moment, but is easily extensible. It can also function with no +VCS at all. .. _Arch: http://www.gnu.org/software/gnu-arch/ .. _Bazaar: http://bazaar.canonical.com/ @@ -29,7 +29,8 @@ Contents: distributed_bugtracking.txt hacking.txt spam.txt - libbe.txt + libbe/libbe.txt + doc.txt Indices and tables ================== diff --git a/doc/libbe.bug.txt b/doc/libbe.bug.txt deleted file mode 100644 index 41427c5..0000000 --- a/doc/libbe.bug.txt +++ /dev/null @@ -1,7 +0,0 @@ -**************** -:mod:`libbe.bug` -**************** - -.. automodule:: libbe.bug - :members: - :undoc-members: diff --git a/doc/libbe.bugdir.txt b/doc/libbe.bugdir.txt deleted file mode 100644 index 2464ea6..0000000 --- a/doc/libbe.bugdir.txt +++ /dev/null @@ -1,7 +0,0 @@ -******************* -:mod:`libbe.bugdir` -******************* - -.. automodule:: libbe.bugdir - :members: - :undoc-members: diff --git a/doc/libbe.comment.txt b/doc/libbe.comment.txt deleted file mode 100644 index 6e76f98..0000000 --- a/doc/libbe.comment.txt +++ /dev/null @@ -1,7 +0,0 @@ -******************** -:mod:`libbe.comment` -******************** - -.. automodule:: libbe.comment - :members: - :undoc-members: diff --git a/doc/libbe.txt b/doc/libbe.txt deleted file mode 100644 index 5d29434..0000000 --- a/doc/libbe.txt +++ /dev/null @@ -1,14 +0,0 @@ -************ -:mod:`libbe` -************ - -.. automodule:: libbe - :members: - :undoc-members: - -.. toctree:: - :maxdepth: 2 - - libbe.bugdir.txt - libbe.bug.txt - libbe.comment.txt diff --git a/libbe/bug.py b/libbe/bug.py index dd68518..8bf32dd 100644 --- a/libbe/bug.py +++ b/libbe/bug.py @@ -122,9 +122,9 @@ load_status(active_status_def, inactive_status_def) class Bug (settings_object.SavedSettingsObject): """A bug (or issue) is a place to store attributes and attach - :class:`libbe.comment.Comment`\s. In mailing-list terms, a bug is + :class:`~libbe.comment.Comment`\s. In mailing-list terms, a bug is analogous to a thread. Bugs are normally stored in - :class:`libbe.bugdir.BugDir`\s. + :class:`~libbe.bugdir.BugDir`\s. >>> b = Bug() >>> print b.status diff --git a/libbe/bugdir.py b/libbe/bugdir.py index fa8edb9..9328b06 100644 --- a/libbe/bugdir.py +++ b/libbe/bugdir.py @@ -88,7 +88,7 @@ class DiskAccessRequired (Exception): class BugDir (list, settings_object.SavedSettingsObject): - """A BugDir is a container for :class:`libbe.bug.Bug`\s, with some + """A BugDir is a container for :class:`~libbe.bug.Bug`\s, with some additional attributes. See :class:`SimpleBugDir` for some bugdir manipulation exampes. diff --git a/libbe/command/assign.py b/libbe/command/assign.py index 2430d23..6abf05e 100644 --- a/libbe/command/assign.py +++ b/libbe/command/assign.py @@ -24,7 +24,7 @@ import libbe.command.util class Assign (libbe.command.Command): - """Assign an individual or group to fix a bug + u"""Assign an individual or group to fix a bug >>> import sys >>> import libbe.bugdir diff --git a/libbe/command/serve.py b/libbe/command/serve.py index 43e07cc..7a98a47 100644 --- a/libbe/command/serve.py +++ b/libbe/command/serve.py @@ -293,9 +293,6 @@ class AuthenticationApp (WSGI_Object): def authenticate(self, environ): """Handle user-authentication sent in the 'Authorization' header. - Basic HTTP/1.0 Authentication - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - This function implements ``Basic`` authentication as described in HTTP/1.0 specification [1]_ . Do not use this module unless you are using SSL, as it transmits unencrypted passwords. diff --git a/libbe/comment.py b/libbe/comment.py index 003bf71..d8632a4 100644 --- a/libbe/comment.py +++ b/libbe/comment.py @@ -100,7 +100,7 @@ def save_comments(bug): class Comment (Tree, settings_object.SavedSettingsObject): - """Comments are a notes that attach to :class:`libbe.bug.Bug`\s in + """Comments are a notes that attach to :class:`~libbe.bug.Bug`\s in threaded trees. In mailing-list terms, a comment is analogous to a single part of an email. |