Update docs structure. (#2693)

* Update docs structure. * change deployment repo usage * Update deployment repo doc * Fix mkdocs issues Co-authored-by: Liza Shakury <[email protected]>
microsoft · Oct 23, 2022 · 30f0030 · 30f0030
1 parent 4e0342b
commit 30f0030
Show file tree

Hide file tree

Showing 8 changed files with 46 additions and 82 deletions.
diff --git a/docs/using-tre/pipelines/pipelines.md → ...-instructions/deploying-azure-tre-cicd.md b/docs/using-tre/pipelines/pipelines.md → ...-instructions/deploying-azure-tre-cicd.md
diff --git a/docs/tre-admins/setup-instructions/deployment-repo.md b/docs/tre-admins/setup-instructions/deployment-repo.md
@@ -0,0 +1,29 @@
+# AzureTRE Deployment repo
+
+AzureTRE has an OSS deployment repository which you can find [here.](https://github.com/microsoft/AzureTRE-Deployment)
+It contains all the required tooling to develop your custom templates and deploy the Azure TRE:
+
+- Github Actions implementing AzureTRE automation, including running deployments to Azure
+- Configuration specific to deployment
+- Directories setup for: workspace, workspace service and user resource template definitions
+- Devcontainer setup
+
+## AzureTRE Reference
+
+AzureTRE deployment repository allows you to reference AzureTRE as a folder, but also uses it in its deployment. See [AzureTRE Deployment readme](https://github.com/microsoft/AzureTRE-Deployment) to learn more about it.
+
+## Getting Started
+
+To get started with AzureTRE follow the next steps:
+
+1. Go to [AzureTRE Deployment repository](https://github.com/microsoft/AzureTRE-Deployment)
+1. Click on use this template to set up your project from this template:
+
+[![Use AzureTRE Deployment template](../../assets/using-tre/use_template.png)](../../assets/using-tre/use_template.png)
+
+1. Follow the steps in this [Github templates guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) to set up the repo.
+
+
+## Next steps
+
+* [AD Tenant Choices](./ad-tenant-choices.md)
diff --git a/docs/tre-admins/setup-instructions/installing-base-workspace.md b/docs/tre-admins/setup-instructions/installing-base-workspace.md
@@ -48,6 +48,7 @@ As explained in the [auth guide](../auth.md), every workspace has a correspondin
 
 Running the script will report `WORKSPACE_API_CLIENT_ID` and `WORKSPACE_API_CLIENT_SECRET` for the generated app. Copy these into `/templates/core/.env` so that automated testing will work. You also need to use `WORKSPACE_API_CLIENT_ID` in the POST body below.
 
+### Create workspace using the API
 Go to `https://<azure_tre_fqdn>/api/docs` and use POST `/api/workspaces` with the sample body to create a base workspace.
 
 ```json

diff --git a/docs/tre-admins/setup-instructions/prerequisites.md b/docs/tre-admins/setup-instructions/prerequisites.md
@@ -19,33 +19,7 @@ The files for the dev container are located in `/.devcontainer/` folder.
 !!! tip
     An alternative of running the development container locally is to use [GitHub Codespaces](https://docs.github.com/en/codespaces).
 
-## Clone the Azure TRE Git repository
-
-!!! tip
-    If using Windows please clone the repository to a Linux file system, i.e. to `/xxx` rather than `c:\`, for example within Windows Subsytem for Linux. If you clone the repository to a Windows file system you will likely hit issues with file permissions as described in this issue: <https://github.com/microsoft/AzureTRE/issues/1395>
-
-  ```cmd
-  git clone https://github.com/microsoft/AzureTRE.git
-  ```
-
-  The Git repository will host some basic configuration for the TRE instances that are deployed from a given repository. Create a new branch for the instance that you are about to deploy.
-
-  ```cmd
-  cd AzureTRE
-  git checkout -b quickstartenv
-  ```
-
-1. Open the cloned repository in Visual Studio Code and connect to the development container.
-
-  ```cmd
-  code .
-  ```
-
-!!! tip
-    Visual Studio Code should recognize the available development container and ask you to open the folder using it. For additional details on connecting to remote containers, please see the [Open an existing folder in a container](https://code.visualstudio.com/docs/remote/containers#_quick-start-open-an-existing-folder-in-a-container) quickstart.
-
-When you start the development container for the first time, the container will be built. This usually takes a few minutes.
 
 ## Next steps
 
-* [AD Tenant Choices](./ad-tenant-choices.md)
+* [AzureTRE Deployment Repository](./deployment-repo.md)
diff --git a/docs/using-tre/upgrading-tre/index.md → docs/tre-admins/upgrading-tre.md b/docs/using-tre/upgrading-tre/index.md → docs/tre-admins/upgrading-tre.md
@@ -4,14 +4,14 @@ This document will cover how AzureTRE is referenced and how to upgrade its versi
 
 ## Introduction
 
-AzureTRE referenced as an external folder in [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment). A specific version of it is downloaded as part of devcontainer setup.
+AzureTRE referenced as an external folder in [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment) (which is used as a template for your project in the quickstart guide). A specific version of AzureTRE is downloaded as part of devcontainer setup.
  A symlink is then created making it available to reference in the directory itself (it is available only for reference, any changes to it are gitignored)
 
 ## How to upgrade AzureTRE version
 
 Select AzureTRE version:
 1. In AzureTRE go to releases:
-    ![Go to AzureTRE releases](../../assets/using-tre/select_release.png)
+    ![Go to AzureTRE releases](../assets/using-tre/select_release.png)
 1. Choose a release version
 
 To upgrade AzureTRE version inside [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment):

diff --git a/docs/using-tre/index.md b/docs/using-tre/index.md
@@ -1,46 +1,3 @@
 # Using the Azure TRE
 
-This documentation part will cover how to use AzureTRE, extend it with your custom images and deploy it.
-
-## AzureTRE deployment repo
-
-AzureTRE has an OSS deployment repository which you can find [here.](https://github.com/microsoft/AzureTRE-Deployment)
-It contains all the required tooling to develop your custom templates and deploy the Azure TRE:
-
-- Github Actions implementing AzureTRE automation, including running deployments to Azure
-- Configuration specific to deployment
-- Directories setup for: workspace, workspace service and user resource template definitions
-- Devcontainer setup
-
-### AzureTRE Reference
-
-AzureTRE deployment repository allows you to reference AzureTRE as a folder, but also uses it in its deployment. See [AzureTRE Deployment readme](https://github.com/microsoft/AzureTRE-Deployment) to learn more about it.
-
-## Getting Started
-
-To get started with AzureTRE follow the next steps:
-
-1. Go to [AzureTRE Deployment repository](https://github.com/microsoft/AzureTRE-Deployment)
-1. Click on use this template to set up your project from this template:
-
-[![Use AzureTRE Deployment template](../assets/using-tre/use_template.png)](../assets/using-tre/use_template.png)
-
-1. Follow the steps in this [Github templates guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) to set up the repo.
-1. Having the project setup in your account, follow the next steps and guides to setup and extend AzureTRE in your environment:
-    - [Local Development](local-development/local-development.md)
-    - Setup [CI/CD pipelines](pipelines/pipelines.md)
-    - Add your [custom templates](templates/index.md)
-
-## How to Contribute to our Documentation
-
-If you have any comments or suggestions about our documentation then you can visit our GitHub project and either raise a new issue, or comment on one of the existing ones.
-
-You can find our existing documentation issues on GitHub by clicking on the link below:
-
-[Existing Documentation Issues](https://github.com/microsoft/AzureTRE/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
-
-Or, you can raise a new issue by clicking on this link:
-
-[Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose)
-
-**Thank you for your patience and support!**
+This section contains information relevant on how to use AzureTRE.
diff --git a/docs/using-tre/templates/index.md b/docs/using-tre/templates/index.md
@@ -32,7 +32,8 @@ See [template authoring guide](../../tre-workspace-authors/authoring-workspace-t
 
 ## Publish and Register Custom templates in the CI/CD
 
-See the [pipelines documentation](../pipelines/pipelines.md) to learn more about publishing and registering your custom templates as part of the CI/CD/
+See the [pipelines documentation](../../tre-admins/setup-instructions/deploying-azure-tre-cicd.md) to learn more about publishing and registering your custom templates as part of the CI/CD/
+
 ## How to Contribute to our Documentation
 
 If you have any comments or suggestions about our documentation then you can visit our GitHub project and either raise a new issue, or comment on one of the existing ones.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -56,12 +56,15 @@ nav:
   - QuickStart: # Setup steps for anyone performing an initial deployment of the AzureTRE for eval purposes
       - tre-admins/setup-instructions/index.md
       - 1. Prerequisites: tre-admins/setup-instructions/prerequisites.md
-      - 2. AD Tenant: tre-admins/setup-instructions/ad-tenant-choices.md
-      - 3. Pre-deployment Steps: tre-admins/setup-instructions/pre-deployment-steps.md
-      - 4. Deploying Azure TRE: tre-admins/setup-instructions/deploying-azure-tre.md
-      - 5. Configuring Shared Services: tre-admins/setup-instructions/configuring-shared-services.md
-      - 6. Installing Base Workspace: tre-admins/setup-instructions/installing-base-workspace.md
-      - 7. Installing Workspace Service and User Resource: tre-admins/setup-instructions/installing-workspace-service-and-user-resource.md
+      - 2. AzureTRE Deployment Repository: tre-admins/setup-instructions/deployment-repo.md
+      - 3. AD Tenant: tre-admins/setup-instructions/ad-tenant-choices.md
+      - 4. Pre-deployment Steps: tre-admins/setup-instructions/pre-deployment-steps.md
+      - 5. Deploying Azure TRE:
+          - Manual Deployment: tre-admins/setup-instructions/deploying-azure-tre.md
+          - Deploying the AzureTRE using CI/CD: tre-admins/setup-instructions/deploying-azure-tre-cicd.md
+      - 6. Configuring Shared Services: tre-admins/setup-instructions/configuring-shared-services.md
+      - 7. Installing Base Workspace: tre-admins/setup-instructions/installing-base-workspace.md
+      - 8. Installing Workspace Service and User Resource: tre-admins/setup-instructions/installing-workspace-service-and-user-resource.md
 
   - Using the Azure TRE: # Documentation for users of the TRE
       - Introduction: using-tre/index.md
@@ -109,6 +112,7 @@ nav:
                   - Automation Test Account: tre-admins/identities/test-account.md
                   - Workspaces: tre-admins/identities/workspace.md
           - Registring Templates: tre-admins/registering-templates.md
+          - Upgrading AzureTRE version: tre-admins/upgrading-tre.md
 
       - Development: # Docs related to the developing code for the AzureTRE
           - Local Development: using-tre/local-development/local-development.md
@@ -129,8 +133,6 @@ nav:
                   - Overview: tre-templates/pipeline-templates/overview.md
                   - Pipeline Schema: tre-templates/pipeline-templates/pipeline-schema.md
 
-      - Deploying the AzureTRE using CI/CD: using-tre/pipelines/pipelines.md
-
       - Troubleshooting FAQ: # General Troubleshooting Section for Development
           - troubleshooting-faq/index.md
           - Enabling Debugging for the API: troubleshooting-faq/debug-api.md
-Original file line number
+Diff line change
@@ Expand Up @@
     Running the script will report `WORKSPACE_API_CLIENT_ID` and `WORKSPACE_API_CLIENT_SECRET` for the generated app. Copy these into `/templates/core/.env` so that automated testing will work. You also need to use `WORKSPACE_API_CLIENT_ID` in the POST body below.
+    ### Create workspace using the API
     Go to `https://<azure_tre_fqdn>/api/docs` and use POST `/api/workspaces` with the sample body to create a base workspace.
     ```json
@@ Expand Down @@