Updated docs to avoid broken pull requests.

Updated GitHub Pages doc with examples that avoid broken pull requests.

Travis doesn't set encrypted env vars during pull requests and ssh-add
was prompting for a password since the decrypted key was bad. This
caused tests to time out.

Since this is kind of important, making root-ref master instead of
greatest tag until the next release (hopefully I don't forget).

Got rid of backticks, not my style.

.travis.yml

@@ -18,11 +18,11 @@ before_script:
 script: tox -e $TOX_ENV
 after_success:
   - coveralls
-  - touch docs/key; chmod 600 docs/key  # Secure before storing key data.
-  - openssl aes-256-cbc -K $encrypted_9c2bf3fbb9ea_key -iv $encrypted_9c2bf3fbb9ea_iv -in docs/key.enc -out docs/key -d
-  - eval `ssh-agent -s`; ssh-add docs/key
+  - eval "$(ssh-agent -s)"; touch docs/key; chmod 0600 docs/key
+  - openssl aes-256-cbc -d -K "$encrypted_9c2bf3fbb9ea_key" -iv "$encrypted_9c2bf3fbb9ea_iv" < docs/key.enc > docs/key
+    && ssh-add docs/key
   - git remote set-url origin "git@github.com:$TRAVIS_REPO_SLUG"
-  - export ${!TRAVIS*}  # For commit messages.
+  - export ${!TRAVIS*}
   - tox -e docsV
 
 # Deploy.

README.rst

@@ -42,6 +42,12 @@ Changelog
 
 This project adheres to `Semantic Versioning <http://semver.org/>`_.
 
+Unreleased
+----------
+
+Fixed
+    * https://github.com/Robpol86/sphinxcontrib-versioning/issues/5
+
 1.0.1 - 2016-08-02
 ------------------
 

docs/github_pages.rst

@@ -119,20 +119,31 @@ travis.yml
 ----------
 
 The ``travis encrypt-file`` command should have updated your ``.travis.yml`` with the openssl command for you. However
-we still need to make one more change to the file before committing it. Update .travis.yml with these ``chmod``,
-``eval``, and ``git remote`` commands. The after_success section should end up looking like this:
+we still need to make one more change to the file before committing it. Update .travis.yml to make the after_success
+section look like this:
 
 .. code-block:: bash
 
     after_success:
-      - touch docs/key; chmod 600 docs/key  # Secure before storing key data.
-      - openssl aes-256-cbc ... -in docs/key.enc -out docs/key -d
-      - eval `ssh-agent -s`; ssh-add docs/key
+      - eval "$(ssh-agent -s)"; touch docs/key; chmod 0600 docs/key
+      - openssl aes-256-cbc -d -K "$encrypted_key" -iv "$encrypted_iv" < docs/key.enc > docs/key
+        && ssh-add docs/key  # Use && to prevent ssh-add from prompting during pull requests.
       - git config --global user.email "builds@travis-ci.com"
       - git config --global user.name "Travis CI"
       - git remote set-url origin "git@github.com:$TRAVIS_REPO_SLUG"
       - export ${!TRAVIS*}  # Optional, for commit messages.
       - sphinx-versioning push gh-pages . docs
 
+.. warning::
+
+    Always conditionally run ssh-add only if openssl succeeds like in the example above. Encrypted environment variables
+    are not set on Travis CI and probably other CIs during pull requests for security reasons. If you always run ssh-add
+    (which appears to be what everyone does) all of your pull requests will have failing tests because:
+
+    #. Travis CI runs all commands in after_success even if one fails.
+    #. openssl appears to copy "key.enc" to "key" when it fails to decrypt.
+    #. ssh-add will prompt for a passphrase because it thinks the file is encrypted with an SSH passphrase.
+    #. The Travis job will hang, timeout, and fail even if tests pass.
+
 Finally commit both **.travis.yml** and the encrypted **docs/key.enc** file. Push and watch Travis update your docs
 automatically for you.

tox.ini

@@ -48,7 +48,7 @@ deps =
 
 [testenv:docsV]
 commands =
-    sphinx-versioning -t -S semver,chrono -e .gitignore -e .nojekyll -e README.rst push gh-pages . docs -- -W
+    sphinx-versioning -S semver,chrono -e .gitignore -e .nojekyll -e README.rst push gh-pages . docs -- -W
 deps =
     {[testenv:docs]deps}
 passenv =