[PATCH] docs: Document the various management commands available

[Stephen Finucane]

As requested.

Signed-off-by: Stephen Finucane <stephen at that.guru>
Reported-by: Thomas Monjalon <thomas.monjalon at 6wind.com>
Closes-bug: #77
---
 docs/deployment/installation.rst      |   6 ++
 docs/deployment/management.rst        | 134 ++++++++++++++++++++++++++++++++++
 docs/index.rst                        |   1 +
 docs/usage/overview.rst               |   2 +
 patchwork/management/commands/cron.py |   2 +-
 5 files changed, 144 insertions(+), 1 deletion(-)
 create mode 100644 docs/deployment/management.rst

diff --git a/docs/deployment/installation.rst b/docs/deployment/installation.rst
index 16cb41f..a570dd8 100644
--- a/docs/deployment/installation.rst
+++ b/docs/deployment/installation.rst
@@ -500,6 +500,8 @@ different sites and their corresponding domain names, which is required for the
 different emails sent by Patchwork (registration, password recovery) as well as
 the sample `pwclientrc` files provided by your project's page.
 
+.. _deployment-parsemail:
+
 Incoming Email
 --------------
 
@@ -635,6 +637,8 @@ services can be more than to get email into Patchwork.
 You can also create such as service yourself using a PaaS provider that
 supports incoming mail and writing a little web app.
 
+.. _deployment-vcs:
+
 (Optional) Configure your VCS to Automatically Update Patches
 -------------------------------------------------------------
 
@@ -653,6 +657,8 @@ If you are using a system other than Git, you can likely write a similar hook
 using `pwclient` to update patch state. If you do write one, please contribute
 it.
 
+.. _deployment-cron:
+
 (Optional) Configure the Patchwork Cron Job
 -------------------------------------------
 
diff --git a/docs/deployment/management.rst b/docs/deployment/management.rst
new file mode 100644
index 0000000..f173273
--- /dev/null
+++ b/docs/deployment/management.rst
@@ -0,0 +1,134 @@
+Management
+==========
+
+This document describes the myriad administrative commands available with
+Patchwork. Many of these commands are referenced in the :doc:`development
+<../development/installation>` and :doc:`deployment <installation>`
+installation guides.
+
+The ``manage.py`` Script
+------------------------
+
+Django provides the ``django-admin`` command-line utility for interacting with
+Django applications and projects, as described in the `Django documentation`_.
+Patchwork, being a Django application, provides a wrapper for this command -
+``manage.py`` - that exposes not only the management commands of Django and its
+default applications, but also a number of custom, Patchwork-only management
+commands.
+
+An overview of the Patchwork-specific commands is provided below. For
+information on the commands provided by Dhango itself, refer to the `Django
+documentation`_. Information on any command can also be found by passing the
+``--help`` parameter:
+
+.. code-block:: shell
+
+   ./manage.py cron --help
+
+.. _Django documentation: https://docs.djangoproject.com/en/1.8/ref/django-admin/
+
+Available Commands
+------------------
+
+cron
+~~~~
+
+.. program:: manage.py cron
+
+.. code-block:: shell
+
+   ./manage.py cron
+
+Run periodic Patchwork functions: send notifications and expire unused users.
+
+This is required to ensure notifications emails are actually sent to users that
+request them. For more information on integration of this script, refer to the
+:ref:`deployment installation guide <deployment-cron>`.
+
+parsearchive
+~~~~~~~~~~~~
+
+.. program:: manage.py parseachive
+
+Parse an mbox archive file and store any patches/comments found.
+
+.. code-block:: shell
+
+   ./manage.py parsearchive [--list-id <list-id>] <infile>
+
+This is mostly useful for development or for adding message that were missed
+due to, for example, an outage.
+
+.. option:: --list-id <list-id>
+
+   mailing list ID. If not supplied, this will be extracted from the mail
+   headers.
+
+.. option:: infile
+
+   input mbox filename
+
+parsemail
+~~~~~~~~~
+
+.. program:: manage.py parsemail
+
+Parse an mbox file and store any patch/comment found.
+
+.. code-block:: shell
+
+   ./manage.py parsemail [--list-id <list-id>] <infile>
+
+This is the main script used to get mails (and therefore patches) into
+Patchwork. It is generally used by the ``parsemail.sh`` script in combination
+with a mail transfer agent (MTA) like Postfix. For more information, refer to
+the :ref:`deployment installation guide <deployment-parsemail>`.
+
+.. option:: --list-id <list-id>
+
+   mailing list ID. If not supplied, this will be extracted from the mail
+   headers.
+
+.. option:: infile
+
+   input mbox filename. If not supplied, a patch will be read from ``stdin``.
+
+rehash
+~~~~~~
+
+.. program:: manage.py rehash
+
+Update the hashes on existing patches.
+
+.. code-block:: shell
+
+   ./manage.py rehash [<patch_id>, ...]
+
+Patchwork stores hashes for each patch it receives. These hashes can be used to
+uniquely identify a patch for things like :ref:`automatically changing the
+state of the patch in Patchwork when it merges <deployment-vcs>`. If you change
+your hashing algorithm, you may wish to rehash the patches.
+
+.. option:: patch_id
+
+   a patch ID number. If not supplied, all patches will be updated.
+
+retag
+~~~~~
+
+.. program:: manage.py retag
+
+Update the tag (Ack/Review/Test) counts on existing patches.
+
+.. code-block:: shell
+
+  ./manage.py retag [<patch_id>...]
+
+Patchwork extracts :ref:`tags <overview-tags>` from each patch it receives. By
+default, three tags are extracted, but it's possible to change this on a
+per-instance basis. Should you add additional tags, you may wish to scan older
+patches for these new tags.
+
+.. option:: patch_id
+
+   a patch ID number. If not supplied, all patches will be updated.
diff --git a/docs/index.rst b/docs/index.rst
index 623b683..5a7bcda 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ of community projects.
 
    deployment/installation
    deployment/configuration
+   deployment/management
    deployment/upgrading
 
 .. _development-docs:
diff --git a/docs/usage/overview.rst b/docs/usage/overview.rst
index 40f49e1..6d9117c 100644
--- a/docs/usage/overview.rst
+++ b/docs/usage/overview.rst
@@ -105,6 +105,8 @@ one delegate can be assigned to a patch.
    Patchwork supports automatic delegation of patches. Refer to
    :doc:`delegation` for more information.
 
+.. _overview-tags:
+
 Tags
 ~~~~
 
diff --git a/patchwork/management/commands/cron.py b/patchwork/management/commands/cron.py
index e3e906a..2be234b 100644
--- a/patchwork/management/commands/cron.py
+++ b/patchwork/management/commands/cron.py
@@ -24,7 +24,7 @@ from patchwork.notifications import send_notifications
 
 
 class Command(BaseCommand):
-    help = ('Run periodic patchwork functions: send notifications and '
+    help = ('Run periodic Patchwork functions: send notifications and '
             'expire unused users')
 
     def handle(self, *args, **kwargs):
-- 
2.9.4