Handle DOCUMENTER_KEY errors better in deploydocs

* Print a more helpful error if base64decode fails for the provided key.
* Use SSH batch mode -- this means that SSH won't ask for passphrase
  and time out the Travis build if the SSH key is problematic.
* Also, print a more helpful error if git fetch throws an error, most
  likely due to a key misconfiguration.

Closes #697

.travis.yml

@@ -2,12 +2,12 @@ language: julia
 
 os:
   - linux
-  - osx
+  #- osx
 
 julia:
-  - 0.7
+  #- 0.7
   - 1.0
-  - nightly
+  #- nightly
 
 notifications:
   email: false
@@ -23,7 +23,11 @@ jobs:
       os: linux
       script:
         - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
-        - julia --project=docs/ docs/make.jl
+        - |
+          julia --project=docs/ -e'
+            ENV["DOCUMENTER_KEY"]="blah"
+            include("docs/make.jl")
+          '
       after_success: skip
     - stage: "Documentation/PDF"
       julia: 1.0

docs/make.jl

@@ -54,4 +54,6 @@ makedocs(
 deploydocs(
     repo = "github.com/JuliaDocs/Documenter.jl.git",
     target = "build",
+    branch = "gh-pages-test",
+    devbranch = "mp/fix-697",
 )

src/Documenter.jl

@@ -547,13 +547,22 @@ function git_push(
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
 
-    keyfile = abspath(joinpath(root, ".documenter"))
     target_dir = abspath(target)
 
     # The upstream URL to which we push new content and the ssh decryption commands.
     upstream = "git@$(replace(repo, "github.com/" => "github.com:"))"
 
-    write(keyfile, String(base64decode(key)))
+    keyfile = abspath(joinpath(root, ".documenter"))
+    try
+        write(keyfile, String(base64decode(key)))
+    catch e
+        @error """
+        Documenter failed to decode the DOCUMENTER_KEY environment variable.
+        Make sure that the environment variable is properly set up as a Base64-encoded string
+        of the SSH private key. You may need to re-generate the keys with DocumenterTools.
+        """
+        rethrow(e)
+    end
     chmod(keyfile, 0o600)
 
     try
@@ -564,6 +573,7 @@ function git_push(
                 StrictHostKeyChecking no
                 HostName github.com
                 IdentityFile $keyfile
+                BatchMode yes
             """
         ) do
             cd(temp) do
@@ -574,7 +584,17 @@ function git_push(
 
                 # Fetch from remote and checkout the branch.
                 run(`git remote add upstream $upstream`)
-                run(`git fetch upstream`)
+                try
+                    run(`git fetch upstream`)
+                catch e
+                    @error """
+                    Git failed to fetch $upstream
+                    This can be caused by a DOCUMENTER_KEY variable that is not correctly set up.
+                    Make sure that the environment variable is properly set up as a Base64-encoded string
+                    of the SSH private key. You may need to re-generate the keys with DocumenterTools.
+                    """
+                    rethrow(e)
+                end
 
                 try
                     run(`git checkout -b $branch upstream/$branch`)