Deploy to any branch

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

@@ -83,7 +83,7 @@ def internal(arg, **kwargs):
             exclusive_grp.add_argument(arg, **kwargs)
         else:
             parser.add_argument(arg, **kwargs)
-            
+
     return internal
 
 
@@ -126,7 +126,6 @@ def get_parser(config=None):
     if we do not appear to be on Travis.""")
     deploy_parser_add_argument('deploy_directory', type=str, nargs='?',
         help="""Directory to deploy the html documentation to on gh-pages.""")
-
     deploy_parser_add_argument('--token', action='store_true', default=False,
         help="""Push to GitHub using a personal access token. Use this if you
         used 'doctr configure --token'.""")
@@ -135,6 +134,9 @@ def get_parser(config=None):
     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=None,
+                               help="""Name of the branch to deploy to (default: 'master' for ``*.github.io``
+                               repos, 'gh-pages' otherwise)""")
     deploy_parser_add_argument('--tmp-dir', default=None,
         help=argparse.SUPPRESS)
     deploy_parser_add_argument('--deploy-repo', default=None, help="""Repo to
@@ -160,7 +162,7 @@ def get_parser(config=None):
         compatibility.""")
 
     if config:
-        print('Warning, The following options in `.travis.yml` were not recognised:\n%s' % json.dumps(config, indent=2))
+        print('Warning, The following options in `.travis.yml` were not recognized:\n%s' % json.dumps(config, indent=2))
 
     configure_parser = subcommand.add_parser('configure', help="Configure doctr. This command should be run locally (not on Travis).")
     configure_parser.set_defaults(func=configure)
@@ -237,15 +239,20 @@ def deploy(args, parser):
     build_repo = get_current_repo()
     deploy_repo = args.deploy_repo or build_repo
 
+    if args.deploy_branch_name:
+        deploy_branch = args.deploy_branch_name
+    else:
+        deploy_branch = 'master' if deploy_dir.endswith(('.github.io', '.github.com')) else 'gh-pages'
+
     current_commit = subprocess.check_output(['git', 'rev-parse', 'HEAD']).decode('utf-8').strip()
     try:
-
         branch_whitelist = {'master'} if args.require_master else set({})
         branch_whitelist.update(set(config.get('branches',set({}))))
 
-        can_push = setup_GitHub_push(deploy_repo, auth_type='token' if args.token else
-                             'deploy_key', full_key_path=args.key_path,
-                             branch_whitelist=branch_whitelist)
+        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,
+                                     branch_whitelist=branch_whitelist)
 
         if args.sync:
             built_docs = args.built_docs or find_sphinx_build_dir()
@@ -265,7 +272,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

@@ -133,7 +133,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=None, branch_whitelist=None):
+def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github_deploy_key.enc', require_master=None, branch_whitelist=None, deploy_branch='gh-pages'):
     """
     Setup the remote to push to GitHub (to be run on Travis).
 
@@ -206,50 +206,56 @@ 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 with name specified in ``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.
+    Note that default ``deploy_branch`` is ``gh-pages`` for regular repos and
+    ``master`` for ``github.io`` repos.
 
+    This isn't completely robust. If there are multiple remotes and you have a
+    ``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 with name specified in ``deploy_branch``,
+    create one.
+
+    Note that default ``deploy_branch`` is ``gh-pages`` for regular
+    repos and ``master`` for ``github.io`` repos.
 
-    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', '-'])
 
@@ -330,7 +336,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.
@@ -381,9 +387,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
@@ -392,6 +398,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])