Improve documentation on the kittystore-* commands

1 files changed, 37 insertions, 6 deletions

diff --git a/doc/database.rst b/doc/database.rst
index 6ef8cba..1c822e6 100644
--- a/doc/database.rst
+++ b/doc/database.rst
@@ -22,13 +22,44 @@ The scheme may be "sqlite", "postgres", or "mysql". For example, with sqlite::
 
     KITTYSTORE_URL = "sqlite:////path/to/hyperkitty/directory/kittystore.db'
 
-Then, you can run ``kittystore-import`` to import existing archives into the
-mailman database. Thoses archives can be downloaded by calling
-``kittystore-download21``. If you're installing hyperkitty on the machine which
-hosted the previous version of mailman, the archives are already available
-locally and you can use them directly.
-
 .. note::
     If you're using SQLite and you're getting "Database is locked" errors, stop
     your webserver during the import.
 
+
+Importing the current archives
+==============================
+
+If you are currently running Mailman 2.1, you can run ``kittystore-import`` to
+import existing archives into the mailman database. This command will import
+the Mbox files: if you're installing hyperkitty on the machine which hosted the
+previous version of mailman, those files are available locally and you can use
+them directly.
+
+The command's syntax is::
+
+    kittystore-import --settings MODULE --pythonpath PATH -l NAME mbox_file [mbox_file ...]
+
+where:
+
+* ``MODULE`` is the python module with HyperKitty's Django settings,
+* ``PATH`` is an additionnal path to add to Python if the settings module can't be
+  imported directly (this should be familiar if you know how to use Django's
+  ``django-admin`` command)
+* ``NAME`` is the fully-qualified list name (including the ``@`` sign and the
+  domain name)
+* The ``mbox_file`` arguments are the existing archives to import.
+
+If the previous archives aren't available locally, you need to download them
+from your current Mailman 2.1 installation. The ``kittystore-download21``
+command can help you do that, its syntax is::
+
+    kittystore-download21 -u URL -l LIST_NAME [-d destdir]
+
+where:
+
+* ``URL`` is the base URL of your current Mailman 2.1 installation, typically
+  the part before the ``/pipermail`` subdirectory when you're looking at your
+  current archives.
+* ``LIST_NAME`` is the name of the mailing-list without the domain (before the
+  ``@`` sign)