docs: def setup_GitHub_push(deploy_repo, *, auth_type='deploy_key',
      full_key_path='github_deploy_key.enc', require_master=None,
      branch_whitelist=None, deploy_branch='gh-pages',
      env_name='DOCTR_DEPLOY_ENCRYPTION_KEY', build_tags=False):
      """
      Setup the remote to push to GitHub (to be run on Travis).
  
      ``auth_type`` should be either ``'deploy_key'`` or ``'token'``.
  
      For ``auth_type='token'``, this sets up the remote with the token and
      checks out the gh-pages branch. The token to push to GitHub is assumed to be in the ``GH_TOKEN`` environment
      variable.
  
      For ``auth_type='deploy_key'``, this sets up the remote with ssh access.
      """
      # Set to the name of the tag for tag builds
      TRAVIS_TAG = os.environ.get("TRAVIS_TAG", "")
  
      if branch_whitelist is None:
          branch_whitelist={'master'}
  
      if require_master is not None:
          import warnings
          warnings.warn("`setup_GitHub_push`'s `require_master` argument in favor of `branch_whitelist=['master']`",
                  DeprecationWarning,
                  stacklevel=2)
          branch_whitelist.add('master')
  
      if auth_type not in ['deploy_key', 'token']:
          raise ValueError("auth_type must be 'deploy_key' or 'token'")
  
      TRAVIS_BRANCH = os.environ.get("TRAVIS_BRANCH", "")
      TRAVIS_PULL_REQUEST = os.environ.get("TRAVIS_PULL_REQUEST", "")
  
      # Check if the repo is a fork
      TRAVIS_REPO_SLUG = os.environ["TRAVIS_REPO_SLUG"]
      REPO_URL = 'https://api.github.com/repos/{slug}'
      r = requests.get(REPO_URL.format(slug=TRAVIS_REPO_SLUG))
      fork = r.json().get('fork', False)
  
      canpush = determine_push_rights(
          branch_whitelist=branch_whitelist,
          TRAVIS_BRANCH=TRAVIS_BRANCH,
          TRAVIS_PULL_REQUEST=TRAVIS_PULL_REQUEST,
          fork=fork,
          TRAVIS_TAG=TRAVIS_TAG,
          build_tags=build_tags)
  
      print("Setting git attributes")
      set_git_user_email()
  
      remotes = subprocess.check_output(['git', 'remote']).decode('utf-8').split('\n')
      if 'doctr_remote' in remotes:
          print("doctr_remote already exists, removing")
          run(['git', 'remote', 'remove', 'doctr_remote'])
      print("Adding doctr remote")
      if canpush:
          if auth_type == 'token':
              token = get_token()
              run(['git', 'remote', 'add', 'doctr_remote',
                  'https://{token}@github.com/{deploy_repo}.git'.format(token=token.decode('utf-8'),
                      deploy_repo=deploy_repo)])
          else:
              keypath, key_ext = full_key_path.rsplit('.', 1)
              key_ext = '.' + key_ext
              try:
                  setup_deploy_key(keypath=keypath, key_ext=key_ext, env_name=env_name)
              except RuntimeError:
                  # Rate limits prevent this check from working every time. By default, we
                  # assume it isn't a fork so that things just work on non-fork builds.
                  if r.status_code == 403:
                      print(yellow("Warning: GitHub's API rate limits prevented doctr from detecting if this build is a forked repo. If it is, you may ignore the 'DOCTR_DEPLOY_ENCRYPTION_KEY environment variable is not set' error that follows. If it is not, you should re-run 'doctr configure'. Note that doctr cannot deploy from fork builds due to limitations in Travis."), file=sys.stderr)
                  raise
  
              run(['git', 'remote', 'add', 'doctr_remote',
                  'git@github.com:{deploy_repo}.git'.format(deploy_repo=deploy_repo)])
      else:
          print('setting a read-only GitHub doctr_remote')
          run(['git', 'remote', 'add', 'doctr_remote',
                  'https://github.com/{deploy_repo}.git'.format(deploy_repo=deploy_repo)])
  
  
      print("Fetching doctr remote")
      run(['git', 'fetch', 'doctr_remote'])
  
      return canpush