Wiki restructuring - interoperability

docs/wiki/Home.md

@@ -59,7 +59,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the
   - [Pipeline usage](./The%20CI%20environment%20-%20Pipeline%20usage)
 - [Interoperability](./Interoperability)
   - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion)
-  - [Register ADO pipelines](./Interoperability%20-%20Register%20ADO%20pipelines)
+  - [Register Azure DevOps pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20pipelines)
 - [Contribution guide](./Contribution%20guide)
   - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme)
   - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles)

docs/wiki/Interoperability - Bicep to ARM conversion.md

@@ -0,0 +1,31 @@
+Bicep is a relatively new Domain-specific language (DSL) and, at the time of writing, not yet in version 1.0.0. For this reason, some people may want to wait for Bicep's _General Availability_ and prefer to use ARM/JSON for the time being.
+
+For these scenarios, the CARML library provides a script that uses the Bicep Toolkit translator/compiler to support the conversion of CARML Bicep modules to ARM/JSON Templates.
+This page documents the conversion utility and how to use it.
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [How it works](#what-it-does)
+- [How to use it](#how-to-use-it)
+
+---
+# Location
+
+You can find the script under `/utilities/tools/ConvertTo-ARMTemplate.ps1`
+
+# How it works
+
+The script finds all `deploy.bicep` files and converts them to json-based ARM templates by using the following steps:
+1. Remove existing deploy.json files from folders where deploy.bicep files are also present.
+1. Convert .bicep files to .json
+1. Remove bicep metadata from the coverted .json files
+1. Remove .bicep files and folders
+1. Update pipeline files - Replace .bicep with .json in pipeline files
+
+# How to use it
+
+For details on how to use the function please refer to the script's local documentation.
+> **Note:** The script must be loaded before the function can be invoked

docs/wiki/Interoperability - Register Azure DevOps Pipelines.md

@@ -0,0 +1,40 @@
+Not all customers may be using GitHub repos and/or GitHub Actions. CARML can be hosted in a GitHub repo and deployed using Azure DevOps Pipelines or run entirely through Azure DevOps.
+
+Use this script to automatically register all specified Azure DevOps pipelines in a target Azure DevOps project. This is especially useful to register the initial module pipelines as there is one for each module in the repository.
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [How it works](#what-it-does)
+- [How to use it](#how-to-use-it)
+
+---
+# Location
+
+You can find the script under `/utilities/tools/AzureDevOps/Register-AzureDevOpsPipeline.ps1`
+
+# How it works
+
+1. Get all pipelines in a given target folder (for example `.azuredevops/modulePipelines`)
+1. Fetch all currently registered pipelines in the target Azure DevOps project
+1. Compare the local defined and remote-registered pipelines to detect which need to be created and which skipped
+1. Create all pipelines that are missing
+1. Optionally register the pipelines also for build validation (i.e. they registered to be required for Pull Requests)
+
+# How to use it
+
+> **Note:** You'll need the 'azure-devops' extension to run this function: `az extension add --upgrade -n azure-devops`
+
+The steps you'd want to follow are
+1. (if pipelines are in GitHub) Create a service connection to the target GitHub repository using e.g. oAuth
+1. Create a PAT token for the Azure DevOps environment in which you want to register the pipelines in
+1. Run this script with the corresponding input parameters
+1. Create any required element required to execute the pipelines. For example:
+   - Library group(s) used in the pipeline(s)
+   - Service connection(s) used in the pipeline(s)
+   - Agent pool(s) used in the pipeline(s) if not using the default available agents
+
+For further details on how to use the function please refer to the script's local documentation.
+> **Note:** The script must be loaded before the function can be invoked

docs/wiki/Interoperability.md

@@ -0,0 +1,11 @@
+This section explores how CARML can work with both Bicep & ARM JSON templates as well as GitHub Actions & Azure DevOps Pipelines to meet different customer scenarios.
+
+This is how you will run different scripts and set up a module in either ARM JSON Template or Bicep syntax and configure a CI/CD pipeline using Azure DevOps or GitHub.
+
+---
+
+### _Navigation_
+- [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion)
+- [Register Azure DevOps pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20pipelines)
+
+---