api-doc readme and script comments

api-docs/README.md

@@ -1,7 +1,36 @@
 ## Generate InfluxDB API docs
+InfluxDB uses [Redoc](https://github.com/Redocly/redoc/) and
+[redoc-cli](https://github.com/Redocly/redoc/blob/master/cli/README.md) to generate
+API documentation from the InfluxDB `swagger.yml`.
 
-- Versioned swagger files
+To minimize repo size, the generated API documentation HTML is gitignored, therefore
+not committed directly to the docs repo.
+The InfluxDB docs deployment process uses swagger files in the `api-docs` directory
+to generate version-specific API documentation.
 
+### Versioned swagger files
+Structure versions swagger files using the following pattern:
 ```
+api-docs/
+  ├── v2.0/
+  │     └── swagger.yml
+  ├── v2.1/
+  │     └── swagger.yml
+  ├── v2.2/
+  │     └── swagger.yml
+  └── etc...
+```
+
+### Generate API docs locally
+Because the API documentation HTML is gitignored, you must manually generate it
+to view the API docs locally.
+
+From the root of the docs repo, run:
+
+```sh
+# Install redoc-cli
 npm install -g redoc-cli
+
+# Generate the API docs
+cd api-docs && generate-api-docs.sh
 ```

api-docs/generate-api-docs.sh

@@ -35,6 +35,8 @@ weight: 102
   # Create temp file with frontmatter and Redoc html
   echo "$frontmatter" >> $version.tmp
   cat redoc-static.html >> $version.tmp
+
+  # Remove redoc file and move the tmp file to it's proper place
   rm -f redoc-static.html
   mv $version.tmp ../content/$version/api.html
 done