diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/conf.py | 9 | ||||
| -rw-r--r-- | doc/generate-libbe-txt.py | 25 | ||||
| -rw-r--r-- | doc/hacking.txt | 47 | ||||
| -rw-r--r-- | doc/index.txt | 18 | ||||
| -rw-r--r-- | doc/install.txt | 18 | ||||
| -rw-r--r-- | doc/tutorial.txt | 23 |
6 files changed, 83 insertions, 57 deletions
diff --git a/doc/conf.py b/doc/conf.py index 1090a28..371480e 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.autosummary', + 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'numpydoc'] # Add any paths that contain templates here, relative to this directory. @@ -196,3 +197,9 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +# -- Options for Intersphinx --------------------------------------------------- + +intersphinx_mapping = { + 'http://docs.python.org/dev': None, + } diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py index 35eb5c4..b5145ee 100644 --- a/doc/generate-libbe-txt.py +++ b/doc/generate-libbe-txt.py @@ -1,6 +1,21 @@ #!/usr/bin/python # -# Copyright +# Copyright (C) 2010 W. Trevor King <wking@drexel.edu> +# +# This file is part of Bugs Everywhere. +# +# Bugs Everywhere 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. +# +# Bugs Everywhere 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 Bugs Everywhere. If not, see <http://www.gnu.org/licenses/>. """Auto-generate reStructuredText of the libbe module tree for Sphinx. """ @@ -34,10 +49,10 @@ def toctree(children): ' %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') +def make_module_txt(modname, children, subdir='libbe'): + filename = os.path.join(subdir, '%s.txt' % modname) + if not os.path.exists(subdir): + os.mkdir(subdir) if os.path.exists(filename): return None # don't overwrite potentially hand-written files. f = file(filename, 'w') diff --git a/doc/hacking.txt b/doc/hacking.txt index 5b075f9..54be7bc 100644 --- a/doc/hacking.txt +++ b/doc/hacking.txt @@ -6,15 +6,19 @@ Adding commands =============== To write a plugin, you simply create a new file in the -``libbe/commands/`` directory. Take a look at one of the simpler -plugins (e.g. ``remove.py``) for an example of how that looks, and to -start getting a feel for the libbe interface. +:file:`libbe/command/` directory. Take a look at one of the simpler +plugins (e.g. :mod:`libbe.command.remove`) for an example of how that +looks, and to start getting a feel for the libbe interface. -See ``libbe/commands/base.py`` for the definition of the important -classes ``Option``, ``Argument``, ``Command``, ``InputOutput``, -``StorageCallbacks``, and ``UserInterface`` classes. You'll be -subclassing ``Command`` for your command, but all those classes will -be important. +See :mod:`libbe.command.base` for the definition of the important +classes :class:`~libbe.command.base.Option`, +:class:`~libbe.command.base.Argument`, +:class:`~libbe.command.base.Command`, +:class:`~libbe.command.base.InputOutput`, +:class:`~libbe.command.base.StorageCallbacks`, and +:class:`~libbe.command.base.UserInterface`. You'll be subclassing +:class:`~libbe.command.base.Command` for your command, but all those +classes will be important. Command completion @@ -22,21 +26,22 @@ Command completion BE implements a general framework to make it easy to support command completion for arbitrary plugins. In order to support this system, -any of your completable ``Argument()`` instances (in your command's -``.options`` or ``.args``) should be initialized with some valid -completion_callback function. Some common cases are defined in -``libbe.command.util``. If you need more flexibility, see -``libbe.command.list``'s ``--sort`` option for an example of -extensions via ``libbe.command.util.Completer``, or write a custom -completion function from scratch. +any of your completable :class:`~libbe.command.base.Argument` +instances (in your command's ``.options`` or ``.args``) should be +initialized with some valid completion_callback function. Some common +cases are defined in :mod:`libbe.command.util`. If you need more +flexibility, see :mod:`libbe.command.list`\'s ``--sort`` option for an +example of extensions via :class:`libbe.command.util.Completer`, or +write a custom completion function from scratch. Adding user interfaces ====================== -Take a look at ``libbe/ui/command_line.py`` for an example. Basically -you'll need to setup a ``UserInterface`` instance for running commands. -More details to come after I write an HTML UI... +Take a look at :mod:`libbe.ui.command_line` for an example. +Basically you'll need to setup a +:class:`~libbe.command.base.UserInterface` instance for running +commands. More details to come after I write an HTML UI... Testing @@ -50,11 +55,11 @@ for example: be$ python test.py libbe.command.merge -For a definition of "any tests", see ``test.py``'s +For a definition of "any tests", see :file:`test.py`'s ``add_module_tests()`` function. Note that you will need to run ``make`` before testing a clean BE -branch to auto-generate required files like ``libbe/_version.py``. +branch to auto-generate required files like :file:`libbe/_version.py`. Profiling @@ -71,5 +76,5 @@ It's often useful to toss:: import sys, traceback print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) -into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if +into expensive functions (e.g. :func:`libbe.util.subproc.invoke`) if you're not sure why they're being called. diff --git a/doc/index.txt b/doc/index.txt index 30b0318..77e756e 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -21,15 +21,15 @@ Contents: .. toctree:: :maxdepth: 2 - install.txt - tutorial.txt - email.txt - html.txt - distributed_bugtracking.txt - hacking.txt - spam.txt - libbe/libbe.txt - doc.txt + install + tutorial + email + html + distributed_bugtracking + hacking + spam + libbe/libbe + doc Indices and tables ================== diff --git a/doc/install.txt b/doc/install.txt index b1d153e..796d163 100644 --- a/doc/install.txt +++ b/doc/install.txt @@ -2,19 +2,19 @@ Installing BE ************* -Bazaar repository -================= +Git repository +============== -BE is available as a bzr repository:: +BE is available as a Git repository:: - $ bzr branch http://bzr.bugseverywhere.org/be + $ git clone git://gitorious.org/be/be.git be -See the homepage_ for details. If you do branch the bzr repo, you'll +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:: +to build some auto-generated files (e.g. :mod:`libbe._version`), and:: $ make install @@ -29,9 +29,9 @@ Release tarballs ================ For those not interested in the cutting edge, or those who don't want -to worry about installing Bazaar, we'll post release tarballs somewhere -(once we actually make a release). After you've downloaded the release -tarball, unpack it with:: +to worry about installing Git, we'll post release tarballs somewhere +(once we actually make a release). After you've downloaded the +release tarball, unpack it with:: $ tar -xzvf be-<VERSION>.tar.gz diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 7932c9c..592aef5 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -15,16 +15,15 @@ and helps keep the bug repository in sync with the code. However, there are some differences compared to centralized bugtrackers. Because bugs and comments can be created by several -users in parallel, they have globally unique IDs_ rather than numbers. -There is also a developer-friendly command-line_ interface to -compliment the user-friendly web_ and email_ interfaces. This -tutorial will focus on the command-line interface as the most -powerful, and leave the web and email interfaces to other documents. +users in parallel, they have globally unique +:mod:`IDs </libbe.util.id>` rather than numbers. There is also a +developer-friendly command-line_ interface to compliment the +user-friendly :doc:`web </tutorial-html>` and +:doc:`email </tutorial-email>` interfaces. This tutorial will focus +on the command-line interface as the most powerful, and leave the web +and email interfaces to other documents. .. _command-line: `Command-line interface`_ -.. _web: tutorial-html.txt -.. _email: tutorial-email.txt -.. _IDs: libbe/libbe.util.id.txt Installation ============ @@ -39,13 +38,13 @@ Bugs If you have any problems with BE, you can look for matching bugs:: - $ be --repo http://bugseverywhere.org/bugs list + $ be --repo http://bugs.bugseverywhere.org/ list If your bug isn't listed, please open a new bug:: - $ be --repo http://bugseverywhere.org/bugs new 'bug' + $ be --repo http://bugs.bugseverywhere.org/ new 'bug' Created bug with ID bea/abc - $ be --repo http://bugseverywhere.org/bugs comment bea/def + $ be --repo http://bugs.bugseverywhere.org/ comment bea/def <editor spawned for comments> @@ -266,7 +265,7 @@ Compare with a previous revision ``480``:: Compare your BE branch with the trunk:: - $ be diff --repo http://bugseverywhere.org/bugs/ + $ be diff --repo http://bugs.bugseverywhere.org/ Manipulating bugs ----------------- |