[deploy] Avoid stable/master doc deployment from non-master via flag

bob/devtools/deploy.py

@@ -78,8 +78,8 @@ def deploy_conda_package(package, arch, stable, public, username, password,
     davclient.upload(local_path=package, remote_path=remote_path)
 
 
-def deploy_documentation(path, package, stable, public, branch, tag, username,
-    password, dry_run):
+def deploy_documentation(path, package, stable, latest, public, branch, tag,
+    username, password, dry_run):
   '''Deploys sphinx documentation to the appropriate webdav locations
 
   Args:
@@ -88,6 +88,11 @@ def deploy_documentation(path, package, stable, public, branch, tag, username,
     package (str): Full name (with namespace) of the package being treated
     stable (bool): Indicates if the documentation corresponds to the latest
       stable build
+    latest (bool): Indicates if the documentation being deployed correspond to
+      the latest stable for the package or not.  In case the documentation
+      comes from a patch release which is not on the master branch, please set
+      this flag to ``False``, which will make us avoid deployment of the
+      documentation to ``master`` and ``stable`` sub-directories.
     public (bool): Indicates if the documentation is supposed to be distributed
       publicly or privatly (within Idiap network)
     branch (str): The name of the branch for the current build
@@ -120,10 +125,11 @@ def deploy_documentation(path, package, stable, public, branch, tag, username,
   # "stable" subdir as well
   deploy_docs_to = set([branch])
   if stable:
-    deploy_docs_to.add('master')
     if tag is not None:
       deploy_docs_to.add(tag)
-    deploy_docs_to.add('stable')
+    if latest:
+      deploy_docs_to.add('master')
+      deploy_docs_to.add('stable')
 
   # creates package directory, and then uploads directory there
   for k in deploy_docs_to:

bob/devtools/scripts/ci.py

@@ -86,14 +86,27 @@ Examples:
 
      $ bdt ci deploy -vv
 
+
+  2. Deploys stable release from non-master branch (e.g. you're releasing a patch release for an older version of a package):
+
+     $ bdt ci deploy -vv --no-latest
+
 ''')
+@click.option('-n', '--latest/--no-latest', default=True,
+    help='If set (the default), for stable builds, deploy documentation ' \
+        'to both "stable" and "master" branches, besides "<branch>" and ' \
+        '"<tag>" - otherwise, only deploys documentation to "<branch>" ' \
+        'and "<tag>".  This option is useful if you are publishing ' \
+        'corrections of a release from a stable branch which is **NOT** ' \
+        'the master branch, so you would not like to overwrite ' \
+        'documentation deployments for "stable" and "master"')
 @click.option('-d', '--dry-run/--no-dry-run', default=False,
     help='Only goes through the actions, but does not execute them ' \
         '(combine with the verbosity flags - e.g. ``-vvv``) to enable ' \
         'printing to help you understand what will be done')
 @verbosity_option()
 @bdt.raise_on_error
-def deploy(dry_run):
+def deploy(latest, dry_run):
     """Deploys build artifacts (conda packages and sphinx documentation)
 
     Deployment happens at the "right" locations - conda packages which do not
@@ -129,8 +142,8 @@ def deploy(dry_run):
             overwrite=False, dry_run=dry_run)
 
     local_docs = os.path.join(os.environ['CI_PROJECT_DIR'], 'sphinx')
-    deploy_documentation(local_docs, package, stable=stable, public=public,
-        branch=os.environ['CI_COMMIT_REF_NAME'],
+    deploy_documentation(local_docs, package, stable=stable, latest=latest,
+        public=public, branch=os.environ['CI_COMMIT_REF_NAME'],
         tag=os.environ.get('CI_COMMIT_TAG'), username=os.environ['DOCUSER'],
         password=os.environ['DOCPASS'], dry_run=dry_run)