Update publishing docs and API information (#372)

Some environment variables can be set by the CircleCI build itself
Document `USE_SSH`

docs/api-commands.md

@@ -74,11 +74,26 @@ Alias: `publish-gh-pages`
 
 [Builds](api-commands.md#docusaurus-build), then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:
 
+The following is generally set manually by the user in the CircleCI `config.yml` file.
+
  - `GIT_USER`: The git user to be associated with the deploy commit.
+ - `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
+
+ e.g.,
+
+ ```bash
+ GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
+ ```
+
+The following are set by the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/) during the build process.
+
  - `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run.
+ - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
+
+The following should be set by you in `siteConfig.js` as `organizationName` and `projectName`, respectively. If they are not set in your site configuration, they fall back to the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/).
+
  - `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the git repo, e.g. "facebook".
  - `CIRCLE_PROJECT_REPONAME`: The name of the git repo, e.g. "Docusaurus".
- - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
 
 You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md).
 

docs/getting-started-publishing.md

@@ -42,9 +42,11 @@ One of the required parameters is set as a environment variable:
 
 - `GIT_USER`: The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username.
 
-There is also an optional parameter that is set as an environment variable. If nothing is set for this variable, then the current branch will be used.
+There are also two optional parameters that are set as environment variables:
 
-- `CURRENT_BRANCH`: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`.
+- `USE_SSH`: If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set.
+
+- `CURRENT_BRANCH`: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used.
 
 > Docusaurus also supports deploying user or organization sites. Just set your project name to "_username_.github.io" (where _username_ is your username or organization name on GitHub) and the publish script will automatically deploy your site to the root of the `master` branch instead.
 
@@ -52,9 +54,10 @@ Once you have the parameter value information, you can go ahead and run the publ
 
 To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.
 
-```
+```bash
 GIT_USER=<GIT_USER> \
   CURRENT_BRANCH=master \
+  USE_SSH=true \
   yarn run publish-gh-pages # or `npm run publish-gh-pages`
 ```
 
@@ -106,7 +109,9 @@ Make sure to replace `<GIT_USER>` with the actual username of the GitHub account
 
 **DO NOT** place the actual value of `$GITHUB_TOKEN` in `circle.yml`. We already configured that as an environment variable back in Step 3.
 
-> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the values of `ORGANIZATION_NAME`, `PROJECT_NAME`, and `CURRENT_BRANCH` are already defined as environment variables within CircleCI and will be picked up by the script automatically.
+> If you want to use SSH for your GitHub repo connection, you can set `USE_SSH=true`. So the above command would look something like: `cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages`.
+
+> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the value of `CURRENT_BRANCH` is already defined as an [environment variable within CircleCI](https://circleci.com/docs/1.0/environment-variables/) and will be picked up by the script automatically.
 
 Now, whenever a new commit lands in `master`, CircleCI will run your suite of tests and, if everything passes, your website will be deployed via the `publish-gh-pages` script.