From 4a82e333828dc7a55831e9250be7bcc8b2064e1f Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Tue, 7 Feb 2017 17:21:38 -0500 Subject: [PATCH 1/8] make deploy directory required argument as per discussion in #128, changing the deploy directory to a required argument. the new usage for doctr on the travis side of things would been ``` doctr deploy . ``` to deploy to the root directory on the ``gh-pages`` branch. --- docs/changelog.rst | 5 +++++ doctr/__main__.py | 7 +++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 6cb3b782..27b4a6f4 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -2,6 +2,11 @@ Doctr Changelog ================= +Current +======= +- Change deploy directory to required argument. This is a backwards incompatible change. Default deploy without arguments should now read ``doctr deploy .`` (:issue:`128`) + + 1.4.1 (2017-01-11) ================== - Fix Travis API endpoint when checking if a repo exists. (:issue:`143`) diff --git a/doctr/__main__.py b/doctr/__main__.py index e320576c..96329c5f 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -60,9 +60,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('--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_directory', type=str, + help="""Directory to deploy the html documentation to on gh-pages.""") deploy_parser.add_argument('--tmp-dir', default=None, help=argparse.SUPPRESS) deploy_parser.add_argument('--deploy-repo', default=None, help="""Repo to @@ -251,7 +250,7 @@ def configure(args, parser): - set -e - # Command to build your docs - pip install doctr - - doctr deploy{options} + - doctr deploy{options} {deploy_directory} to the docs build of your .travis.yml. The 'set -e' prevents doctr from running when the docs build fails. Use the 'script' section so that if From da5b224cc5305050706a1b25233a1d2d0b8f2434 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Tue, 7 Feb 2017 19:04:56 -0500 Subject: [PATCH 2/8] make positional argument optional (for now) --- .travis.yml | 6 +++--- doctr/__main__.py | 7 +++++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.travis.yml b/.travis.yml index 0ac8218f..d01017ee 100644 --- a/.travis.yml +++ b/.travis.yml @@ -28,9 +28,9 @@ script: cd docs; make html; cd ..; - python -m doctr deploy --gh-pages-docs . --key-path deploy_key.enc; - python -m doctr deploy --gh-pages-docs docs --key-path deploy_key.enc; - python -m doctr deploy --no-require-master --gh-pages-docs "docs-$TRAVIS_BRANCH" --built-docs docs/_build/html --key-path deploy_key.enc; + python -m doctr deploy --key-path deploy_key.enc .; + python -m doctr deploy --key-path deploy_key.enc docs; + python -m doctr deploy --no-require-master --built-docs docs/_build/html --key-path deploy_key.enc "docs-$TRAVIS_BRANCH"; python -m doctr deploy --no-require-master --key-path deploy_key.enc --no-sync --command "echo test"; fi - if [[ "${TESTS}" == "true" ]]; then diff --git a/doctr/__main__.py b/doctr/__main__.py index 96329c5f..441f2585 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -50,6 +50,8 @@ def get_parser(): subcommand = parser.add_subparsers(title='subcommand', dest='subcommand') deploy_parser = subcommand.add_parser('deploy', help="""Deploy the docs to GitHub from Travis.""") deploy_parser.set_defaults(func=deploy) + deploy_parser.add_argument('deploy_directory', type=str, nargs='?', + help="""Directory to deploy the html documentation to on gh-pages.""") deploy_parser.add_argument('--force', action='store_true', help="""Run the deploy command even if we do not appear to be on Travis.""") deploy_parser.add_argument('--token', action='store_true', default=False, @@ -60,8 +62,6 @@ 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_directory', type=str, - help="""Directory to deploy the html documentation to on gh-pages.""") deploy_parser.add_argument('--tmp-dir', default=None, help=argparse.SUPPRESS) deploy_parser.add_argument('--deploy-repo', default=None, help="""Repo to @@ -80,6 +80,9 @@ def get_parser(): deploy_parser.add_argument('--no-push', dest='push', action='store_false', default=True, help="Run all the steps except the last push step." "Useful for debugging") + deploy_parser.add_argument('--gh-pages-docs', default='docs', + help="""!!DEPRECATED!! Directory to deploy the html documentation to on gh-pages. The + default is %(default)r.""") configure_parser = subcommand.add_parser('configure', help="Configure doctr. This command should be run locally (not on Travis).") From eb68c839c50f14f2bb0a096366648c6d7f075c66 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Wed, 8 Feb 2017 10:24:29 -0500 Subject: [PATCH 3/8] use one deprec. doctr deploy to ensure compatibility to make sure that both methods still work on travis, keeping one of these deploy calls using the old syntax. --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index d01017ee..24f7b9b9 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,7 +29,7 @@ script: make html; cd ..; python -m doctr deploy --key-path deploy_key.enc .; - python -m doctr deploy --key-path deploy_key.enc docs; + python -m doctr deploy --key-path deploy_key.enc --gh-pages-docs docs; python -m doctr deploy --no-require-master --built-docs docs/_build/html --key-path deploy_key.enc "docs-$TRAVIS_BRANCH"; python -m doctr deploy --no-require-master --key-path deploy_key.enc --no-sync --command "echo test"; fi From d4c11f0fcca6fb26ed056ce215087cd60846b6c4 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 8 Feb 2017 20:55:11 -0500 Subject: [PATCH 4/8] Indicate what the flag is deprecated in favor of --- doctr/__main__.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index 441f2585..4edb0be6 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -81,8 +81,10 @@ def get_parser(): default=True, help="Run all the steps except the last push step." "Useful for debugging") deploy_parser.add_argument('--gh-pages-docs', default='docs', - help="""!!DEPRECATED!! Directory to deploy the html documentation to on gh-pages. The - default is %(default)r.""") + help="""!!DEPRECATED!! Directory to deploy the html documentation to on gh-pages. + The default is %(default)r. The deploy directory should be passed as + the first argument to 'doctr deploy'. This flag is kept for backwards + compatibility.""") configure_parser = subcommand.add_parser('configure', help="Configure doctr. This command should be run locally (not on Travis).") From d1ee9baa48c0a095168f2448a33c361ae9a96206 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Thu, 9 Feb 2017 09:26:34 -0500 Subject: [PATCH 5/8] check that only one deploy directory is specified print deprecation warning if `--gh-pages-docs` is used. --- doctr/__main__.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/doctr/__main__.py b/doctr/__main__.py index 4edb0be6..6a9a73bf 100644 --- a/doctr/__main__.py +++ b/doctr/__main__.py @@ -80,7 +80,7 @@ def get_parser(): deploy_parser.add_argument('--no-push', dest='push', action='store_false', default=True, help="Run all the steps except the last push step." "Useful for debugging") - deploy_parser.add_argument('--gh-pages-docs', default='docs', + deploy_parser.add_argument('--gh-pages-docs', default=None, help="""!!DEPRECATED!! Directory to deploy the html documentation to on gh-pages. The default is %(default)r. The deploy directory should be passed as the first argument to 'doctr deploy'. This flag is kept for backwards @@ -129,6 +129,17 @@ def deploy(args, parser): if args.tmp_dir: parser.error("The --tmp-dir flag has been removed (doctr no longer uses a temporary directory when deploying).") + if args.gh_pages_docs: + print("The --gh-pages-docs flag is deprecated and will be removed in the next release. Instead pass the deploy directory as an argument, e.g. `doctr deploy .`") + + if args.gh_pages_docs and args.deploy_directory: + parser.error("The --gh-pages-docs flag is deprecated. Specify the directory to deploy to using `doctr deploy `") + + if not args.gh_pages_docs and not args.deploy_directory: + parser.error("No deploy directory specified. Specify the directory to deploy to using `doctr deploy `") + + deploy_dir = args.gh_pages_docs or args.deploy_directory + build_repo = get_current_repo() deploy_repo = args.deploy_repo or build_repo @@ -141,11 +152,11 @@ def deploy(args, parser): if args.sync: built_docs = args.built_docs or find_sphinx_build_dir() - log_file = os.path.join(args.gh_pages_docs, '.doctr-files') + log_file = os.path.join(deploy_dir, '.doctr-files') print("Moving built docs into place") added, removed = sync_from_log(src=built_docs, - dst=args.gh_pages_docs, log_file=log_file) + dst=deploy_dir, log_file=log_file) else: added, removed = [], [] From e45741418b4e84cad13cf0ea072a3c5e57eb0ab7 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Mon, 20 Feb 2017 11:45:14 -0500 Subject: [PATCH 6/8] missed a deploy location --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 24f7b9b9..b807b054 100644 --- a/.travis.yml +++ b/.travis.yml @@ -31,7 +31,7 @@ script: python -m doctr deploy --key-path deploy_key.enc .; python -m doctr deploy --key-path deploy_key.enc --gh-pages-docs docs; python -m doctr deploy --no-require-master --built-docs docs/_build/html --key-path deploy_key.enc "docs-$TRAVIS_BRANCH"; - python -m doctr deploy --no-require-master --key-path deploy_key.enc --no-sync --command "echo test"; + python -m doctr deploy --no-require-master --key-path deploy_key.enc --no-sync --command "echo test" docs; fi - if [[ "${TESTS}" == "true" ]]; then pyflakes doctr; From bd57a5104574f908fc9fa8c2275043821d700984 Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Sun, 5 Mar 2017 18:11:59 -0500 Subject: [PATCH 7/8] Update changelog.rst --- docs/changelog.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 27b4a6f4..f177893c 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,7 +4,8 @@ Current ======= -- Change deploy directory to required argument. This is a backwards incompatible change. Default deploy without arguments should now read ``doctr deploy .`` (:issue:`128`) +- There is no longer a default deploy directory. Specify the deploy directory + like ``doctr deploy .`` or ``doctr deploy docs``. (:issue:`128`) 1.4.1 (2017-01-11) From ace9bf7615897d8d877f0d9f4c8d2df5977028d1 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 6 Mar 2017 02:42:39 -0500 Subject: [PATCH 8/8] Specify that the --gh-pages-docs flag has been deprecated in the changelog --- docs/changelog.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index f177893c..526b58a1 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,8 +4,9 @@ Current ======= -- There is no longer a default deploy directory. Specify the deploy directory - like ``doctr deploy .`` or ``doctr deploy docs``. (:issue:`128`) +- The ``--gh-pages-docs`` flag of ``doctr deploy`` has been deprecated. + Specify the deploy directory like ``doctr deploy .`` or ``doctr deploy docs``. + There is also no longer a default deploy directory. (:issue:`128`) 1.4.1 (2017-01-11)