Document the deployment procedure

This should clarify some of the details mentioned in the `doctr deploy`
documentation, specifically what "synchronization" is (`--no-sync`
flag), and how `--command` fits in.

Author: goerz

docs/commandline.rst

@@ -6,6 +6,36 @@
    :prog: doctr
 
 
+Deployment Procedure
+--------------------
+
+Starting from a checkout of a white-listed branch on Travis, with the
+documentation having been built successfully, ``doctr deploy`` takes the
+following steps:
+
+* copy the ``BUILT_DOCS`` directory to a temporary location
+* stash the current checkout
+* check out the ``DEPLOY_BRANCH_NAME`` (default ``gh-pages``) on the
+  ``DEPLOY_REPO`` (current repo, by default)
+* "Synchronize":
+   - if there is a file ``.doctr-files`` in the ``deploy_directory``, remove all
+     files listed therein (excluding ``EXCLUDE``)
+   - copy all files from the (copied) ``BUILT_DOCS`` directory to the
+     ``deploy_directory`` (excluding ``EXCLUDE``)
+   - create a new ``.doctr-files`` log that contains all files of the previous
+     ``.doctr-files``, minus those removed, plus those added. That is, a list
+     of all files in the ``deploy_directory`` that exist due to ``doctr``
+* run ``COMMAND`` if ``--command`` was given
+* run ``git add`` for any files that were added during synchronization, and
+  ``git rm`` for any files that were removed
+* commit and push the ``DEPLOY_BRANCH_NAME``
+* switch back to the original checkout and un-stash
+
+As a result of the above procedure, if ``COMMAND`` creates any new files that
+were not present during the synchronization, it must ``git add`` those
+files for them to be committed later.
+
+
 Configuration
 -------------