Mac: Nice warning if you don't have an identity (#637)

Supporting `--all` on mac is "fun" because we rely on ssh auth and, unlike
Linux's lovely bind mounts, macOS can't share the ssh authorization
directly. Instead we have to carefully bounce the ssh authorization into
the container by `ssh`ing into it. One of the steps in this process
requires that the user has an ssh identity configured with their agent.
This is fairly easy to do, but if you haven't done it the error message
was garbage. This catches the original message from `ssh-add` and sends
the user a nicer one that includes a link to instructions.

Author: nik9000

build_docs

@@ -37,6 +37,7 @@ import time
 import webbrowser
 
 DOCKER_BUILD_QUIET_TIME = 3  # seconds
+SSH_AGENT_HELP = 'https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent'  # noqa
 
 DIR = dirname(realpath(__file__))
 logger = logging.getLogger('build_docs')
@@ -250,6 +251,10 @@ def forward_ssh_auth_into_container(container, docker_run):
     handle_popen(get_ssh_public_key, record_public_key)
     keys = "\n".join(public_keys) + "\n"
     if get_ssh_public_key.returncode != 0:
+        if 'The agent has no identities.' in keys:
+            raise ArgError('--all requires an identity be registered with the '
+                           'ssh-agent on macOS. See ' + SSH_AGENT_HELP + ' '
+                           'for instructions.')
         raise subprocess.CalledProcessError(get_ssh_public_key.returncode,
                                             cmd, keys)
 
@@ -451,6 +456,8 @@ if __name__ == '__main__':
         exit(1)
     except subprocess.CalledProcessError as e:
         print(e)
+        if e.output:
+            print(e.output)
         exit(e.returncode)
     except KeyboardInterrupt:
         # Just quit if we get ctrl-c