Many markup fixes in doc/

Also added subdir option to generate-libbe-txt.make_module_txt(), in
the hopes that subdir='.' would fix the missing reference errors, but
no luck (although it did reduce them).  I'm sticking with
subdir='libbe' for now to avoid cluttering doc/ with autogenerated
cruft.

diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py
index 35eb5c4fb2cdd9603c599f5226d2c93fa22bef08..77f775a9afe4ea9a6cbf658ba1cf95bf73f404d7 100644 (file)
--- a/doc/generate-libbe-txt.py
+++ b/doc/generate-libbe-txt.py
@@ -34,10 +34,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 5b075f9a020d17db2a153b17310febf1a5e85fd7..54be7bcda1d0a489d337994e787299763877fb92 100644 (file)
--- 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 30b0318b06e517ef9f92c472aa0a5f565a8ce8f6..77e756eee6f455480f92fe26a869a3930fdf23da 100644 (file)
--- 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 b1d153e68d6478ed0798d86868ff62bdb29752fe..3749189dfb8ed256bcf217dda0e49c45e8e749ff 100644 (file)
--- a/doc/install.txt
+++ b/doc/install.txt
@@ -14,7 +14,7 @@ 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
 

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 7932c9cfc27f4e7fad66d0b33bbcd0fb389517a6..a37b0149fb58d973ed6b3067e33dc649adfff3f0 100644 (file)
--- 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
 ============