diff --git a/docs/rbtools/api/index.txt b/docs/rbtools/api/index.txt
deleted file mode 100644
index c161802d420169d72527882716efddbad711625f..0000000000000000000000000000000000000000
--- a/docs/rbtools/api/index.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-=================
-Python API Client
-=================
-
-Included with RBTools is a Python client for interacting with the Review Board
-Web API.
-
-.. note::
-   This documentation assumes knowledge of the Review Board Web API. When
-   possible links will be provided to relevant sections of the Web API
-   documentation which can be found in the `Web API Guide`_.
-
-.. _`Web API Guide`: http://www.reviewboard.org/docs/manual/dev/webapi/
-
-.. toctree::
-   :maxdepth: 2
-
-   overview
-   tutorial
-   resource-specific
-
-
-.. comment: vim: ft=rst et ts=3
diff --git a/docs/rbtools/index.txt b/docs/rbtools/index.txt
index 1a9d1cff15dff413eff4fa4fba180a33e2f65d9a..b39e154c716d179fdba4ec3592de2de0aca901cc 100644
--- a/docs/rbtools/index.txt
+++ b/docs/rbtools/index.txt
@@ -4,14 +4,62 @@ RBTools Documentation
 
 RBTools is a set of client tools to use with Review Board.
 
-This consists of the following officially supported tools:
+
+Using RBTools
+=============
+
+.. _rbt:
+
+rbt
+---
+
+The recommended command-line interface is the :command:`rbt` tool. This tool
+runs on Windows, Linux, and MacOS X, and allows executing a number of useful
+sub-commands. :command:`rbt` has the following usage::
+
+   $ rbt [--version] <command> [options] [<args>]
+
+The :command:`rbt` command obsoletes the old :command:`post-review` command.
+For built in help you may execute::
+
+   $ rbt help
+
+
+.. toctree::
+   :maxdepth: 2
+
+   rbt/configuration
+   rbt/commands/index
+
+
+post-review
+-----------
+
+:command:`post-review` is an older tool which is now deprecated. See
+:ref:`post-review` for more information.
+
+
+.. _rbtools-api:
+
+Python API
+----------
+
+Included with RBTools is a Python client for interacting with the Review Board
+Web API.
+
+.. note::
+   This documentation assumes knowledge of the Review Board Web API. When
+   possible links will be provided to relevant sections of the Web API
+   documentation which can be found in the `Web API Guide`_.
+
+.. _`Web API Guide`: http://www.reviewboard.org/docs/manual/dev/webapi/
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   rbt/index
-   post-review
-   api/index
+   api/overview
+   api/tutorial
+   api/resource-specific
 
 
 Installation
diff --git a/docs/rbtools/rbt/commands/post.txt b/docs/rbtools/rbt/commands/post.txt
index 134f2720c2b2fc9aac72d89337e91c84a11908a9..cda7e6b7822aa5a2d64a6c7e923dc9003f74289e 100644
--- a/docs/rbtools/rbt/commands/post.txt
+++ b/docs/rbtools/rbt/commands/post.txt
@@ -35,6 +35,36 @@ The following subsections will explain how :command:`rbt post` is used
 with different repository types.
 
 
+.. _automating-rbt-post:
+
+Automating rbt post
+===================
+
+It's possible to automate :command:`rbt post` on a user's behalf. This can
+be useful from a repository's :term:`post-commit hook` to automatically
+create or update a review request. This works through a combination of a
+special Review Board user and the :option:`--submit-as` option.
+
+To set this up, first register a new user. This user will be specific to
+your script, and will have special permissions, so make sure the password
+is protected. You'll then want to grant the
+:ref:`can-submit-as-user-permission` and
+:ref:`can-edit-review-request-permission` to the user. This will give this
+user to the ability to modify a review request as another user.
+
+You can then invoke :command:`rbt post` by doing the following::
+
+    $ rbt post --username=SPECIAL_USER --password=PASSWORD --submit-as=ANOTHER_USER
+
+Of course, you can pass any other values as you see fit.
+
+This will log in as ``SPECIAL_USER`` and perform operations as
+``ANOTHER_USER``.
+
+You can set the default for :option:`--submit-as` by setting ``SUBMIT_AS``
+in :file:`.reviewboardrc`.
+
+
 Perforce
 --------
 
@@ -449,7 +479,9 @@ Options
 .. cmdoption:: --submit-as
 
    Username to be recorded as the author of the review request, instead of the
-   logged in user.
+   logged in user. This is useful when used in a repository's post-commit
+   script to update or create review requests. See :ref:`automating-rbt-post`
+   for information on this use case..
 
    The default can be set in ``SUBMIT_AS`` in :file:`.reviewboardrc`.
 
diff --git a/docs/rbtools/rbt/index.txt b/docs/rbtools/rbt/index.txt
deleted file mode 100644
index 60c8c0b2ca7c9c08380e4b3dc140cda31829fc1e..0000000000000000000000000000000000000000
--- a/docs/rbtools/rbt/index.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-===
-rbt
-===
-
-:command:`rbt` is a command line tool for Windows, Linux and MacOS X
-which allows executing a number of useful sub-commands. :command:`rbt`
-has the following usage::
-
-   $ rbt [--version] <command> [options] [<args>]
-
-The :command:`rbt` command obsoletes the old :command:`post-review` command.
-For built in help you may execute::
-
-   $ rbt help
-
-
-.. toctree::
-   :maxdepth: 2
-
-   configuration
-   commands/index
-
-
-.. comment: vim: ft=rst et ts=3