From 230053331ab91082724e6535d8a99011c8a308ca Mon Sep 17 00:00:00 2001 From: Michael Goerz Date: Sun, 20 Oct 2019 03:03:06 -0400 Subject: [PATCH] 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. --- docs/commandline.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/commandline.rst b/docs/commandline.rst index 58cef768..e60d7086 100644 --- a/docs/commandline.rst +++ b/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 -------------