Merge pull request #3 from TACC-Cloud/doc_changes

Doc changes

docs/agave/guides/apps/app-example-app.rst

@@ -156,7 +156,7 @@ Craft an Agave app description
 
 In order for Agave to know how to run an instance of the application, we need to provide quite a bit of metadata about the application. This includes a unique name and version, the location of the application bundle, the identities of the execution system and destination system for results, whether its an HPC or other kind of job, the default number of processors and memory it needs to run, and of course, all the inputs and parameters for the actual program. It seems a bit over-complicated, but only because you're comfortable with the command line already. Your goal here is to allow your applications to be portable across systems and present a web-enabled, rationalized interface for your code to consumers.
 
-Rather than have you write a description for "samtools sort" from scratch, let's systematically dissect an existing file provided with the SDK. Go ahead and copy the file into place and open it in your text editor of choice. If you don't have the SDK installed, you can `download the JSON descriptions here <samtools-sort.json>`_.
+Rather than have you write a description for "samtools sort" from scratch, let's systematically dissect an existing file provided with the SDK. Go ahead and copy the file into place and open it in your text editor of choice. If you don't have the SDK installed, you can `download the JSON descriptions :raw-html-m2r:`<a href="https://github.com/TACC-Cloud/agave-docs/blob/doc_changes/docs/agave/guides/apps/samtools-sort.json" title="samtools-sort.json">here</a>`_.
 
 .. code-block:: shell
 
@@ -189,7 +189,7 @@ All Agave application descriptions have the following structure:
      "outputs":[]
    }
 
-There is a defined list of application metadata fields, some of which are mandatory. Inputs, parameters, and outputs are specified as an array of simple data structures, which are described earlier in the `Application metadata section <app-wrapper-templates>`_.
+There is a defined list of application metadata fields, some of which are mandatory. Inputs, parameters, and outputs are specified as an array of simple data structures, which are described earlier in the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/apps/app-inputs-and-parameters-tutorial.html" title="Params and Inputs">Application metadata section</a>`.
 
 Inputs
 ------
@@ -224,11 +224,12 @@ To tell Agave what files to stage into place before job execution, you need to d
    }
    }
 
-For information on what these fields mean, see the `Input metadata table <app-wrapper-templates>`_.
+For information on what these fields mean, see the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/apps/app-inputs-and-parameters-tutorial.html" title="Params and Inputs">input metadata table</a>`.
+
 
 ..
 
-   :information_source: A note on paths: In this iPlant-oriented tutorial, we assume you will stage data to and from "data.agaveapi.co", the default storage system for iPlant users. In this case, you can use relative paths relative to homeDir on that system (i.e. vaughn/analyses/foobar). To add portability, marshal data from other storageSystems, or import from public servers, you can also specify fully qualified URIs as follows:
+   :information_source: A note on paths: In this CyVerse-oriented tutorial, we assume you will stage data to and from "data.iplantcollaborative.org", the default storage system for CyVerse users. In this case, you can use relative paths relative to homeDir on that system (i.e. vaughn/analyses/foobar). To add portability, marshal data from other storageSystems, or import from public servers, you can also specify fully qualified URIs as follows:
 
 
    * storageSystem namespace: agave://storage-system-name/path/to/file
@@ -265,7 +266,7 @@ Parameters are specified in a JSON array, and are broadly similar to inputs. Her
      }
    }
 
-For more info on these fields, see `Parameters metadata table <app-wrapper-templates>`_.
+For information on what these fields mean, see the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/apps/app-inputs-and-parameters-tutorial.html" title="Params and Inputs">parameters metadata table</a>`.
 
 Outputs
 -------

docs/agave/guides/apps/app-sharing-apps.rst

@@ -5,7 +5,7 @@
 Permissions
 ===========
 
-Apps have fine grained permissions similar to those found in the `Jobs <../jobs/job-permissions>`_ and `Files <../files/files-permissions>`_ services. Using these, you can share your app other Agave users. App permissions are private by default, so when you first POST your app to the Apps service, you are the only one who can see it. You may share your app with other users by granting them varying degrees of permissions. The full list of app permission values are listed in the following table.
+Apps have fine grained permissions similar to those found in the `Jobs <https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/jobs/job-permissions.html>`_ and `Files <https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/files/files-permissions.html>`_ services. Using these, you can share your app other Agave users. App permissions are private by default, so when you first POST your app to the Apps service, you are the only one who can see it. You may share your app with other users by granting them varying degrees of permissions. The full list of app permission values are listed in the following table.
 
 
 .. raw:: html

docs/agave/guides/apps/app-wrapper-templates.rst

@@ -95,7 +95,7 @@ Agave provides information about the job, system, and user as predefined macros
    </tr>
    <tr>
    <td>AGAVE_JOB_NAME</td>
-   <td>The slugified version of the name of the job. See the section on <a href="../../introduction/conventions">Special Characters</a> for more information about slugs.</td>
+   <td>The slugified version of the name of the job. See the section on <a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/introduction/conventions.html?highlight=special%20characters">Special Characters</a> for more information about slugs.</td>
    </tr>
    <tr>
    <td>AGAVE_JOB_NAME_RAW</td>

docs/agave/guides/authorization/introduction.rst

@@ -143,7 +143,7 @@ The request will include parameters in the query string:
            </tr>
            <tr>
                <td>client_id</td>
-               <td><i>Required</i>. The application's client ID, obtained when the client application was registered with Agave (see <a href="../../documentation/user-guide/client-registration/">Client Registration</a>).</td>
+               <td><i>Required</i>. The application's client ID, obtained when the client application was registered with Agave (see <a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/clients/introduction.html#creating-a-new-client-application">Client Registration</a>).</td>
            </tr>
            <tr>
                <td>redirect_uri</td>
@@ -200,7 +200,7 @@ After the user accepts (or denies) your request, the Agave Authorization service
            </tr>
            <tr>
                <td>access_token </td>
-               <td>An access token that can be provided in subsequent calls, for example to <a href="https://api.tacc.utexas.edu/profiles/v2/me?pretty=true">Agave Profiles API</a>. </td>
+               <td>An access token that can be provided in subsequent calls, for example to Agave Profiles API. </td>
            </tr>
            <tr>
                <td>token_type </td>
@@ -462,7 +462,7 @@ The flow starts off with your application redirecting the user to the ``/authori
            </tr>
            <tr>
                <td>client_id</td>
-               <td><i>Required</i>. The application's client ID, obtained when the client application was registered with Agave (see <a href="../../documentation/user-guide/client-registration/">Client Registration</a>).</td>
+               <td><i>Required</i>. The application's client ID, obtained when the client application was registered with Agave (see <a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/clients/introduction.html#creating-a-new-client-application/">Client Registration</a>).</td>
            </tr>
            <tr>
                <td>redirect_uri</td>

docs/agave/guides/clients/introduction.rst

@@ -14,7 +14,7 @@ Agave uses :raw-html-m2r:`<a href="http://oauth.net/2" title="OAuth2" target="_b
 Creating a new client application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In order to interact with any of the Agave APIs, you will need to first get a set of API keys. You can get your API keys from the :raw-html-m2r:`<a href="http://agaveapi.co/live-docs/#!/clients/create_post_1" title="Clients API">Clients service</a>`. The example below shows how to get your API keys using both curl and the :raw-html-m2r:`<a href="http://agaveapi.co/agave-cli/" title="Agave CLI">Agave CLI</a>`.
+In order to interact with any of the Agave APIs, you will need to first get a set of API keys. You can get your API keys from the Clients service. The example below shows how to get your API keys using both curl and the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/tooling/command-line-interface.html" title="Agave CLI">Agave CLI</a>`.
 
 .. container:: foldable
 
@@ -211,13 +211,13 @@ Listing current subscriptions
         "tier":"Unlimited"
         "_links":{
            "api":{
-              "href":"https://public.tenants.agaveapi.co/files/v2/"
+              "href":"https://api.tacc.utexas.edu/files/v2/"
            },
            "client":{
-              "href":"https://public.tenants.agaveapi.co/clients/v2/systest_test_client"
+              "href":"https://api.tacc.utexas.edu/clients/v2/systest_test_client"
            },
            "self":{
-              "href":"https://public.tenants.agaveapi.co/clients/v2/systest_test_client/subscriptions/"
+              "href":"https://api.tacc.utexas.edu/clients/v2/systest_test_client/subscriptions/"
            }
         }
      },

docs/agave/guides/files/files-metadata.rst

@@ -5,4 +5,4 @@
 File metadata management
 ========================
 
-In many systems, the concept of metadata is directly tied to the notion of a file system. Agave takes a broader view of metadata and supports it as its own first class resource in the REST API. For more information on how to leverage metadata in Agave, please consult the :raw-html-m2r:`<a href="https://tacc.github.io/developer.tacc.cloud/docs/guides/metadata/introduction.html" title="Metadata Tutorial">Metadata Guide</a>`. In there we cover all aspects of how to manage, search, validate, and associate metadata across your entire digital lab.
+In many systems, the concept of metadata is directly tied to the notion of a file system. Agave takes a broader view of metadata and supports it as its own first class resource in the REST API. For more information on how to leverage metadata in Agave, please consult the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/metadata/introduction.html" title="Metadata Tutorial">Metadata Guide</a>`. In there we cover all aspects of how to manage, search, validate, and associate metadata across your entire digital lab.

docs/agave/guides/files/files-permissions.rst

@@ -66,13 +66,13 @@ The response will look something like the following:
        "recursive": true,
        "_links": {
          "self": {
-           "href": "https://tacc.cloud/files/v2/pems/system/api.tacc.cloud/nryan/picksumipsum.txt?username.eq=nryan"
+           "href": "https://api.tacc.utexas.edu/files/v2/pems/system/api.tacc.cloud/nryan/picksumipsum.txt?username.eq=nryan"
          },
          "file": {
-           "href": "https://tacc.cloud/files/v2/media/system/api.tacc.cloud/nryan/picksumipsum.txt"
+           "href": "https://api.tacc.utexas.edu/files/v2/media/system/api.tacc.cloud/nryan/picksumipsum.txt"
          },
          "profile": {
-           "href": "https://tacc.cloud/profiles/v2/nryan"
+           "href": "https://api.tacc.utexas.edu/profiles/v2/nryan"
          }
        }
      }

docs/agave/guides/files/files-publishing.rst

@@ -15,7 +15,7 @@ Notice two things. First, a username is inserted after the *download* path eleme
 
 The following sections give examples of publishing files and folders in the Agave Platform.
 
-See the :raw-html-m2r:`<a href="https://tacc.github.io/developer.tacc.cloud/docs/guides/postits/introduction.html">PostIts Guide</a>` for other ways to securely share your data with others.
+See the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/postits/introduction.html">PostIts Guide</a>` for other ways to securely share your data with others.
 
 Publishing individual files
 ---------------------------
@@ -173,7 +173,7 @@ Publishing an entire directory is identical to publishing a single file item. To
 
  ``https://papi.tacc.utexas.edu/files/v2/download/nryan/system/data.agaveapi.co/nryan/public``
 
-Remember that whenever you publish a folder, anything you put in that folder becomes publicly available. As with any cloud storage service, think before blindly copying data into your cloud storage. If you want to restrict the duration or frequency which your public data is accessed, you should see the :raw-html-m2r:`<a href="#https://tacc.github.io/developer.tacc.cloud/docs/guides/postits/introduction.html">PostIts Guide</a>` for other ways to securely share your data with others.
+Remember that whenever you publish a folder, anything you put in that folder becomes publicly available. As with any cloud storage service, think before blindly copying data into your cloud storage. If you want to restrict the duration or frequency which your public data is accessed, you should see the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/postits/introduction.html">PostIts Guide</a>` for other ways to securely share your data with others.
 
 Publishing considerations
 -------------------------

docs/agave/guides/files/introduction.rst

@@ -91,7 +91,7 @@ One powerful, but potentially confusing feature of Agave is its support for virt
    </table>
 |
 
-``homeDir`` specifies the path, relative to ``rootDir``\ , that Agave should use for relative paths. Since Agave is stateless, there is no concept of a current working directory. Thus, when you specify a path to Agave that does not begin with a ``/``\ , Agave will always prefix the path with the value of ``homeDir``. The following table gives several examples of how different combinations of ``rootDir``\ , ``homeDir``\ , and URL paths will be resolved by Agave. For a deeper dive into this subject, please see the :raw-html-m2r:`<a href="#understanding-agave-file-paths" title="Understanding Agave File Paths">Understanding Agave File Paths</a>` section.
+``homeDir`` specifies the path, relative to ``rootDir``\ , that Agave should use for relative paths. Since Agave is stateless, there is no concept of a current working directory. Thus, when you specify a path to Agave that does not begin with a ``/``\ , Agave will always prefix the path with the value of ``homeDir``. The following table gives several examples of how different combinations of ``rootDir``\ , ``homeDir``\ , and URL paths will be resolved by Agave. 
 
 
 .. raw:: html

docs/agave/guides/jobs/job-monitoring.rst

@@ -9,7 +9,7 @@ Once you submit your job request, the job will be handed off to Agave's back end
 
 ..
 
-   :information_source: For the sake of brevity, we placed a detailed explanation of the job lifecycle in a separate, aptly title post, :raw-html-m2r:`<a href="the-job-lifecycle" title="The Job Lifecycle">The Job Lifecycle</a>`. There you will find detailed information about how, when, and why everything moves from place to place and how you can peek behind the curtains.
+   :information_source: For the sake of brevity, we placed a detailed explanation of the job lifecycle in a separate, aptly title post, :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/jobs/the-job-lifecycle.html" title="The Job Lifecycle">The Job Lifecycle</a>`. There you will find detailed information about how, when, and why everything moves from place to place and how you can peek behind the curtains.
 
 
 Polling
@@ -341,7 +341,7 @@ Webhooks are the alternative, preferred way for your application to monitor the
 
 ..
 
-   :information_source: For more information about webhooks, events, and notifications in Agave, please see the :raw-html-m2r:`<a href="../notifications/introduction" title="Notifications Guide">Notifications</a>` and :raw-html-m2r:`<a href="../events/introduction" title="Events Guide">Events</a>` Guides.
+   :information_source: For more information about webhooks, events, and notifications in Agave, please see the :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/notifications/introduction.html" title="Notifications Guide">Notifications</a>` and :raw-html-m2r:`<a href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/events/introduction.html" title="Events Guide">Events</a>` Guides.
 
 
 The Jobs service provides several template variables for constructing dynamic URLs. Template variables can be included anywhere in your URL by surrounding the variable name in the following manner ``${VARIABLE_NAME}``. When an event of interest occurs, the variables will be resolved and the resulting URL called. Several example urls are given below.

docs/agave/guides/jobs/job-permissions.rst

@@ -5,7 +5,7 @@
 Jobs Permissions and Sharing
 ============================
 
-As with the :raw-html-m2r:`<a title="System Registration" href="../systems/introduction">Systems</a>`\ , :raw-html-m2r:`<a title="Application Management" href="../apps/introduction">Apps</a>`\ , and :raw-html-m2r:`<a title="File Management" href="../files/introduction">Files</a>` services, your jobs have their own set of access controls. Using these, you can share your job and its data with other Agave users. Job permissions are private by default. The permissions you give a job apply both to the job, its outputs, its metadata, and the permissions themselves. Thus, by sharing a job with another user, you share all aspects of that job.
+As with the :raw-html-m2r:`<a title="System Registration" href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/systems/introduction.html">Systems</a>`\ , :raw-html-m2r:`<a title="Application Management" href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/apps/introduction.html">Apps</a>`\ , and :raw-html-m2r:`<a title="File Management" href="https://tacc-cloud.readthedocs.io/projects/agave/en/latest/agave/guides/files/introduction.html">Files</a>` services, your jobs have their own set of access controls. Using these, you can share your job and its data with other Agave users. Job permissions are private by default. The permissions you give a job apply both to the job, its outputs, its metadata, and the permissions themselves. Thus, by sharing a job with another user, you share all aspects of that job.
 
 Job permissions are managed through a set of URLs consistent with the permissions URL elsewhere in the API.