added general content and formatting to docs

wjallen · wjallen · commit 09d629cd65c3 · 2017-09-21T10:59:39.000-05:00
diff --git a/docs/authorization.md b/docs/authorization.md
@@ -1 +1,42 @@
-# Authorization with the SD2E Tenant
+---
+layout: page
+title: Authorization with the SD2E Tenant
+tagline:
+---
+
+Authorization is handled with OAuth2 authorization tokens. You can generate
+a token and save it to your ~/.agave/current configuration file by executing
+the following command:
+```
+%auth-tokens-create -S
+Password:   # enter TACC password
+```
+
+The token is active for 4 hours (14400 seconds), at which point it expires. You
+can check the status of your token by performing:
+```
+% auth-check
+```
+
+When your token expires, there is no need to generate a new token. It can be
+refreshed by using the command:
+```
+% auth-tokens-refresh
+```
+
+<br>
+#### Troubleshooting
+
+If you observe authorization errors with Agave, then first try generating a
+new token with:
+```
+% auth-tokens-create -S
+```
+
+If errors persist, generate a new client:
+```
+% clients-create -S
+```
+
+---
+Return to the [API Documentation Overview](../index.md)
diff --git a/docs/create_client.md b/docs/create_client.md
@@ -1,35 +1,45 @@
-### Create the API Client Key
+---
+layout: page
+title: Create the API Client Key
+tagline:
+---
 
 The Agave CLI is used to configure the user environment to interact with the 
-SD2E platform. If you do not yet have the CLI installed and in your $PATH, first
+SD2E platform. If you do not yet have the CLI installed and in your `$PATH`, first
 go [here](install_cli.md).
 
 Your user environment can be set up in one of two ways:
 1. Automatically using the set up script
 2. Manually using the CLI
 
+<br>
+#### Automatically using the set up script
 
-#### 1. Automatically using the set up script
+(coming soon)
 
-(forthcoming)
-
-#### 2. Manually using the CLI
-
-On the command line, perform the following:
+<br>
+#### Manually using the CLI
 
+On the command line, first initiate with the SD2E tenant:
 ```
-# Initiate with the SD2E tenant
 %tenants-init -t sd2e
 
-# Create a client (enter TACC username and password)
+```
+
+Then, create a client key for interacting with that tenant using your TACC
+credentials:
+```
 %clients-create -S -N my_client -D "My client used for interacting with SD2E"
+Username:   # enter TACC username
+Password:   # enter TACC password
+```
 
-# Create an auth token (enter TACC password)
-%auth-tokens-create -S
 
-# Check the status of the token
-% auth-check
+#### The ~/.agave/current configuration file
 
-# Refresh an expired token:
-% auth-tokens-refresh
-```
+All the information generated above is stored in a configuration file in your 
+home directory. CLI commands can be used to manage different configuration files
+for swapping between tenant and user space.
+
+---
+Return to the [API Documentation Overview](../index.md)
diff --git a/docs/install_cli.md b/docs/install_cli.md
@@ -1,4 +1,8 @@
-### Install and Configure the CLI
+---
+layout: page
+title: Install and Configure the CLI
+tagline:
+---
 
 The primary method for interacting with the SD2E platform is the Agave command
 line interface (CLI). The CLI is a collection of ~150 shell scripts for managing
@@ -9,18 +13,22 @@ There are three methods to install the CLI:
 2. Manual install to a location of your choosing
 3. Pull a CLI Docker image
 
-#### 1. Run an installer script to install in ~/sd2e-cloud-cli/bin/
-
-Open a terminal window and perform the following:
+<br>
+#### Run an installer script to install in ~/sd2e-cloud-cli/bin/
 
+Open a terminal window and run the installer script:
 ```
-# Run the installer
 % curl -L https://raw.githubusercontent.com/sd2e/sd2e-cli/master/install/install.sh | sh
+```
 
-# Source your .bashrc
+This will install the executables and write an `export PATH` command to your
+`~/.bashrc`. To make the changes take effect immediately:
+```
 % source ~/.bashrc
+```
 
-# Verify the CLI is installed
+Finally, verify that the CLI has been installed by issuing the following:
+```
 % sd2e info
 
 DARPA SD2E version 1.0.1
@@ -31,23 +39,29 @@ TACC Cloud API versions:
         TACC Accounting API: v1
 ```
 
-#### 2. Manual install to a location of your choosing
+<br>
+#### Manual install to a location of your choosing
 
-Open a terminal window and perform the following:
+Open a terminal window and navigate to your preferred location for installation:
 
 ```
-# Navigate to a location of your choosing
 % mkdir sd2e-project && cd sd2e-project
+```
 
-# Download and unpack the CLI
+Download and unpack the CLI:
+```
 % curl -L https://raw.githubusercontent.com/sd2e/sd2e-cli/master/sd2e-cloud-cli.tgz -o sd2e-cloud-cli.tgz
 % tar -xvzf sd2e-cloud-cli.tgz
+```
 
-# Add the CLI executables to your $PATH
+Then add the CLI executables to your `PATH`:
+```
 % echo "PATH=\$PATH:$PWD/sd2e-cloud-cli/bin" >> ~/.bashrc
 % source ~/.bashrc
+```
 
-# Verify the CLI is installed
+Finally, verify that the CLI has been installed by issuing the following:
+```
 % sd2e info
 
 DARPA SD2E version 1.0.1
@@ -57,20 +71,36 @@ TACC Cloud API versions:
 	Reactors API: dev
 ```
 
-#### 3. Pull a CLI Docker image
+<br>
+#### Pull a CLI Docker image
 
+The CLI is also available as a Docker image. For this to work, it is assumed you
+have a reasonably recent version of [Docker](https://www.docker.com/) installed.
+Pull the latest image and verify CLI availability by performing:
 ```
-# Pull the latest image
 % docker pull sd2e/cloud-cli:latest
 % docker run -it -v $HOME/.agave:/root/.agave sd2e/cloud-cli bash
 ```
 
-#### Influential environment variables
+Then from within Docker:
+```
+/home$ sd2e info
+
+DARPA SD2E version 1.0.1
+TACC Cloud API tenant: sd2e
+TACC Cloud API versions:
+	Science APIs: 2.2.5
+	Reactors API: dev
+```
 
-AGAVE_TENANT
-AGAVE_USERNAME
-AGAVE_KEY
-AGAVE_JSON_PARSER = json_mirror | jq | json | python | native
-AGAVE_DISABLE_AUTO_REFRESH
+<br>
+#### Influential environment variables
 
+ * AGAVE_TENANT
+ * AGAVE_USERNAME
+ * AGAVE_KEY
+ * AGAVE_JSON_PARSER = {json_mirror, jq, json, python, native}
+ * AGAVE_DISABLE_AUTO_REFRESH
 
+---
+Return to the [API Documentation Overview](../index.md)
diff --git a/docs/request_access.md b/docs/request_access.md
@@ -1,19 +1,32 @@
-### Request Access to the SD2E Platform
+---
+layout: page
+title: Request Access to the SD2E Platform
+tagline:
+---
 
 At this time, access is restricted to SD2 project members. Your username and
-password will be the same as your TACC username and password. To create a TACC
-username and password, visit this site:
+password will be the same as your TACC username and password.
 
-https://portal.tacc.utexas.edu/web/tup/account-request
+<br>
+#### Create a TACC account
+ 
+To create a TACC username and password, visit this site:
+
+<https://portal.tacc.utexas.edu/web/tup/account-request>
 
 You must agree to the TACC Acceptible Use Policy, then fill out the Account
-Request form. Your account request will be reviewd and approved in 1-2 days.
+Request form. Your account request will be reviewed and approved in 1-2 days.
+
+<br>
+#### Request SD2E access
 
 Once you have e-mail confirmation of account creation, send an e-mail including
 your TACC username to:
 
-<blah@tacc.utexas.ed>
+<blah@tacc.utexas.edu>
 
 **Keep your password confidential.** 
 
 
+---
+Return to the [API Documentation Overview](../index.md)
diff --git a/docs/using_api.md b/docs/using_api.md
@@ -1 +1,8 @@
-# Using the SD2E API
+---
+layout: page
+title: Using the SD2E API
+tagline:
+---
+
+---
+Return to the [API Documentation Overview](../index.md)
