add command line argument deploy_branch_name that specifies a target …

doctr/__init__.py

@@ -2,16 +2,16 @@
     generate_GitHub_token, upload_GitHub_deploy_key, generate_ssh_key,
     check_repo_exists)
 from .travis import (decrypt_file, setup_deploy_key, get_token, run,
-    setup_GitHub_push, gh_pages_exists, create_gh_pages, sync_from_log,
+    setup_GitHub_push, deploy_branch_exists, create_deploy_branch, sync_from_log,
     commit_docs, push_docs, get_current_repo, find_sphinx_build_dir)
 
 __all__ = [
     'encrypt_variable', 'encrypt_file', 'GitHub_post',
     'generate_GitHub_token', 'upload_GitHub_deploy_key', 'generate_ssh_key',
     'check_repo_exists',
 
-    'decrypt_file', 'setup_deploy_key', 'get_token', 'run', 'setup_GitHub_push', 'gh_pages_exists',
-    'create_gh_pages', 'sync_from_log', 'commit_docs', 'push_docs', 'get_current_repo', 'find_sphinx_build_dir'
+    'decrypt_file', 'setup_deploy_key', 'get_token', 'run', 'setup_GitHub_push', 'deploy_branch_exists',
+    'create_deploy_branch', 'sync_from_log', 'commit_docs', 'push_docs', 'get_current_repo', 'find_sphinx_build_dir'
 ]
 
 from ._version import get_versions

doctr/__main__.py

@@ -62,6 +62,8 @@ def get_parser():
     deploy_parser.add_argument('--built-docs', default=None,
         help="""Location of the built html documentation to be deployed to
         gh-pages. If not specified, Doctr will try to automatically detect build location""")
+    deploy_parser.add_argument('--deploy-branch-name', default='gh-pages',
+                               help="""Name of branch to deploy to""")
     deploy_parser.add_argument('--tmp-dir', default=None,
         help=argparse.SUPPRESS)
     deploy_parser.add_argument('--deploy-repo', default=None, help="""Repo to
@@ -143,11 +145,14 @@ def deploy(args, parser):
     build_repo = get_current_repo()
     deploy_repo = args.deploy_repo or build_repo
 
+    deploy_branch = args.deploy_branch_name
+
     current_commit = subprocess.check_output(['git', 'rev-parse', 'HEAD']).decode('utf-8').strip()
     try:
-        can_push = setup_GitHub_push(deploy_repo, auth_type='token' if args.token else
-                             'deploy_key', full_key_path=args.key_path,
-                             require_master=args.require_master)
+        can_push = setup_GitHub_push(deploy_repo, deploy_branch=deploy_branch,
+                                     auth_type='token' if args.token else
+                                     'deploy_key', full_key_path=args.key_path,
+                                     require_master=args.require_master)
 
         if args.sync:
             built_docs = args.built_docs or find_sphinx_build_dir()
@@ -167,7 +172,7 @@ def deploy(args, parser):
         changes = commit_docs(added=added, removed=removed)
         if changes:
             if can_push and args.push:
-                push_docs()
+                push_docs(deploy_branch)
             else:
                 print("Don't have permission to push. Not trying.")
         else:

doctr/travis.py

@@ -132,7 +132,7 @@ def get_current_repo():
     _, org, git_repo = remote_url.rsplit('.git', 1)[0].rsplit('/', 2)
     return (org + '/' + git_repo)
 
-def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github_deploy_key.enc', require_master=True):
+def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github_deploy_key.enc', require_master=True, deploy_branch='gh-pages'):
     """
     Setup the remote to push to GitHub (to be run on Travis).
 
@@ -152,8 +152,9 @@ def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github
     TRAVIS_PULL_REQUEST = os.environ.get("TRAVIS_PULL_REQUEST", "")
 
     if TRAVIS_BRANCH != "master" and require_master:
-        print("The docs are only pushed to gh-pages from master. To allow pushing from "
-        "a non-master branch, use the --no-require-master flag", file=sys.stderr)
+        print("The docs are only pushed to {deploy_branch} from master. To allow pushing from "
+              "a non-master branch, use the --no-require-master flag".format(
+                  deploy_branch=deploy_branch), file=sys.stderr)
         print("This is the {TRAVIS_BRANCH} branch".format(TRAVIS_BRANCH=TRAVIS_BRANCH), file=sys.stderr)
         canpush = False
 
@@ -194,50 +195,50 @@ def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github
     print("Fetching doctr remote")
     run(['git', 'fetch', 'doctr_remote'])
 
-    #create gh-pages empty branch with .nojekyll if it doesn't already exist
-    new_gh_pages = create_gh_pages(push=canpush)
-    print("Checking out gh-pages")
-    local_gh_pages_exists = 'gh-pages' in subprocess.check_output(['git', 'branch']).decode('utf-8').split()
-    if new_gh_pages or local_gh_pages_exists:
-        run(['git', 'checkout', 'gh-pages'])
+    #create empty branch with .nojekyll if it doesn't already exist
+    new_deploy_branch = create_deploy_branch(deploy_branch, push=canpush)
+    print("Checking out {}".format(deploy_branch))
+    local_deploy_branch_exists = deploy_branch in subprocess.check_output(['git', 'branch']).decode('utf-8').split()
+    if new_deploy_branch or local_deploy_branch_exists:
+        run(['git', 'checkout', deploy_branch])
     else:
-        run(['git', 'checkout', '-b', 'gh-pages', '--track', 'doctr_remote/gh-pages'])
+        run(['git', 'checkout', '-b', deploy_branch, '--track', 'doctr_remote/{}'.format(deploy_branch)])
     print("Done")
 
     return canpush
 
-def gh_pages_exists():
+def deploy_branch_exists(deploy_branch):
     """
-    Check if there is a remote gh-pages branch.
+    Check if there is a remote branch named ``deploy_branch``.
 
     This isn't completely robust. If there are multiple remotes and you have a
-    ``gh-pages`` branch on the non-default remote, this won't see it.
+    ``deploy_branch`` branch on the non-default remote, this won't see it.
 
     """
     remote_name = 'doctr_remote'
     branch_names = subprocess.check_output(['git', 'branch', '-r']).decode('utf-8').split()
 
-    return '{}/gh-pages'.format(remote_name) in branch_names
+    return '{}/{}'.format(remote_name, deploy_branch) in branch_names
 
-def create_gh_pages(push=True):
+def create_deploy_branch(deploy_branch, push=True):
     """
-    If there is no remote ``gh-pages`` branch, create one.
+    If there is no remote branch named ``deploy_branch``, create one.
 
-    Return True if ``gh-pages`` was created, False if not.
+    Return True if ``deploy_branch`` was created, False if not.
     """
-    if not gh_pages_exists():
-        print("Creating gh-pages branch")
-        run(['git', 'checkout', '--orphan', 'gh-pages'])
+    if not deploy_branch_exists(deploy_branch):
+        print("Creating {} branch".format(deploy_branch))
+        run(['git', 'checkout', '--orphan', deploy_branch])
         # delete everything in the new ref.  this is non-destructive to existing
         # refs/branches, etc...
         run(['git', 'rm', '-rf', '.'])
-        print("Adding .nojekyll file to gh-pages branch")
+        print("Adding .nojekyll file to {} branch".format(deploy_branch))
         run(['touch', '.nojekyll'])
         run(['git', 'add', '.nojekyll'])
-        run(['git', 'commit', '-m', 'Create new gh-pages branch with .nojekyll'])
+        run(['git', 'commit', '-m', 'Create new {} branch with .nojekyll'.format(deploy_branch)])
         if push:
-            print("Pushing gh-pages branch to remote")
-            run(['git', 'push', '-u', 'doctr_remote', 'gh-pages'])
+            print("Pushing {} branch to remote".format(deploy_branch))
+            run(['git', 'push', '-u', 'doctr_remote', deploy_branch])
         # return to master branch
         run(['git', 'checkout', '-'])
 
@@ -318,7 +319,7 @@ def sync_from_log(src, dst, log_file):
 
 def commit_docs(*, added, removed):
     """
-    Commit the docs to ``gh-pages``
+    Commit the docs to the current branch
 
     Assumes that :func:`setup_GitHub_push`, which sets up the ``doctr_remote``
     remote, has been run.
@@ -369,9 +370,9 @@ def commit_docs(*, added, removed):
 
     return False
 
-def push_docs():
+def push_docs(deploy_branch='gh-pages'):
     """
-    Push the changes to the ``gh-pages`` branch.
+    Push the changes to the branch named ``deploy_branch``.
 
     Assumes that :func:`setup_GitHub_push` has been run and returned True, and
     that :func:`commit_docs` has been run. Does not push anything if no changes
@@ -380,6 +381,6 @@ def push_docs():
     """
 
     print("Pulling")
-    run(['git', 'pull', 'doctr_remote', 'gh-pages'])
+    run(['git', 'pull', 'doctr_remote', deploy_branch])
     print("Pushing commit")
-    run(['git', 'push', '-q', 'doctr_remote', 'gh-pages'])
+    run(['git', 'push', '-q', 'doctr_remote', deploy_branch])