From 8f15f84120319146a1de8408b167b9789a875ff6 Mon Sep 17 00:00:00 2001 From: robert Date: Wed, 8 Mar 2017 15:08:37 -0800 Subject: [PATCH 1/9] add command line argument deploy_branch_name that specifies a target branch for the docs on the deploy_repo --- doctr/__main__.py | 13 +++++++---- doctr/travis.py | 59 ++++++++++++++++++++++++----------------------- 2 files changed, 39 insertions(+), 33 deletions(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index e320576c..9ae304c5 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -63,6 +63,8 @@ def get_parser(): deploy_parser.add_argument('--gh-pages-docs', default='docs', help="""Directory to deploy the html documentation to on gh-pages. The default is %(default)r.""") + 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 @@ -128,11 +130,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() @@ -152,7 +157,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: diff --git a/doctr/travis.py b/doctr/travis.py index 3011199a..aa7037c1 100644 --- a/doctr/travis.py +++ b/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, deploy_branch='gh-pages', auth_type='deploy_key', full_key_path='github_deploy_key.enc', require_master=True): """ 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]) From 0eeb989e0efcef04d07ab8bd1a2e4a565e595c85 Mon Sep 17 00:00:00 2001 From: robert Date: Wed, 8 Mar 2017 15:28:43 -0800 Subject: [PATCH 2/9] fixed typo --- doctr/travis.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctr/travis.py b/doctr/travis.py index aa7037c1..19e39931 100644 --- a/doctr/travis.py +++ b/doctr/travis.py @@ -197,7 +197,7 @@ def setup_GitHub_push(deploy_repo, deploy_branch='gh-pages', auth_type='deploy_k #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) + 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]) From 47183e905e667e2aea99e2a150f49980d7baea28 Mon Sep 17 00:00:00 2001 From: robert Date: Wed, 8 Mar 2017 15:49:46 -0800 Subject: [PATCH 3/9] fixed __init__.py, forgot to change import names for functions whose names changed --- doctr/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doctr/__init__.py b/doctr/__init__.py index a0c84a61..5245b4e6 100644 --- a/doctr/__init__.py +++ b/doctr/__init__.py @@ -2,7 +2,7 @@ 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__ = [ @@ -10,8 +10,8 @@ '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 From c4c2d6d07dcaef75dc9b000945ed5f49221a78df Mon Sep 17 00:00:00 2001 From: robert Date: Thu, 9 Mar 2017 10:22:57 -0800 Subject: [PATCH 4/9] preserve argument order for anyone using positional arguments with python api --- doctr/travis.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctr/travis.py b/doctr/travis.py index 19e39931..a80934a2 100644 --- a/doctr/travis.py +++ b/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, deploy_branch='gh-pages', 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). From 3002435a19ae74e4bea424dd5480cc4a5c275d67 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Tue, 14 Mar 2017 16:00:00 -0400 Subject: [PATCH 5/9] autoselect master branch is pushing to github.io repo --- doctr/__main__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index 146aa163..d4bc24a2 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -238,7 +238,7 @@ def deploy(args, parser): build_repo = get_current_repo() deploy_repo = args.deploy_repo or build_repo - deploy_branch = args.deploy_branch_name + deploy_branch = 'master' if deploy_dir.endswith('github.io') else args.deploy_branch_name current_commit = subprocess.check_output(['git', 'rev-parse', 'HEAD']).decode('utf-8').strip() try: From 2d64040d723e4a34ac255a6a0fbbb39fc26cefdc Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Tue, 14 Mar 2017 16:17:54 -0400 Subject: [PATCH 6/9] also deploy to 'master' if 'github.com' site --- doctr/__main__.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index d4bc24a2..dde2a40e 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -134,8 +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='gh-pages', - help="""Name of branch to deploy to""") + 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 @@ -238,7 +239,10 @@ def deploy(args, parser): build_repo = get_current_repo() deploy_repo = args.deploy_repo or build_repo - deploy_branch = 'master' if deploy_dir.endswith('github.io') else args.deploy_branch_name + 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: From 165ecdb0263b29bb33ac05bc13738672b4b9dd51 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Tue, 14 Mar 2017 19:00:38 -0400 Subject: [PATCH 7/9] escape asterisk so sphinx doesn't freak out --- doctr/__main__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index dde2a40e..fe340463 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -135,7 +135,7 @@ def get_parser(config=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 + 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) From 79b9e7dff2d3ddcafcb9da89f55e83017efb06c0 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Wed, 15 Mar 2017 09:15:32 -0400 Subject: [PATCH 8/9] Increase verbiage --- doctr/travis.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doctr/travis.py b/doctr/travis.py index 12815a09..43ded770 100644 --- a/doctr/travis.py +++ b/doctr/travis.py @@ -220,11 +220,12 @@ def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github def deploy_branch_exists(deploy_branch): """ - Check if there is a remote branch named ``deploy_branch``. + Check if there is a remote branch with name specified in ``deploy_branch``. + 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() @@ -233,7 +234,10 @@ def deploy_branch_exists(deploy_branch): def create_deploy_branch(deploy_branch, push=True): """ - If there is no remote branch named ``deploy_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 ``deploy_branch`` was created, False if not. """ From d6e67b4d780417da0a3013299cab1fb9b6df7c44 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Wed, 15 Mar 2017 14:55:41 -0400 Subject: [PATCH 9/9] text fixups --- doctr/__main__.py | 2 +- doctr/travis.py | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index fe340463..94a26810 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -136,7 +136,7 @@ def get_parser(config=None): 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""") + 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 diff --git a/doctr/travis.py b/doctr/travis.py index 43ded770..d292a522 100644 --- a/doctr/travis.py +++ b/doctr/travis.py @@ -221,6 +221,7 @@ def setup_GitHub_push(deploy_repo, auth_type='deploy_key', full_key_path='github def deploy_branch_exists(deploy_branch): """ Check if there is a remote branch with name specified in ``deploy_branch``. + Note that default ``deploy_branch`` is ``gh-pages`` for regular repos and ``master`` for ``github.io`` repos. @@ -236,6 +237,7 @@ def create_deploy_branch(deploy_branch, push=True): """ 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.