Updated Readme.md with Azure Pipelines and GitHub Actions examples (#39)

- Updated the Readme.md with instructions (along with an example) in using Azure Pipelines and GitHub Actions.
BernieWhite · Jan 25, 2021 · ba8548b · ba8548b
1 parent 7617fe9
commit ba8548b
Showing 1 changed file with 106 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -162,6 +162,111 @@ i.e. `templates/storage/v1/template.json`.
 The example finds all the Azure template files and outputs a markdown file for each in `out/docs/`.
 An example of the generated markdown is available [here](templates/storage/v1/README.md)
 
+### Using with Azure Pipelines
+
+The following example shows how to setup Azure Pipelines to generate ARM template documentation in the markdown format.
+This example copies the generated markdown files to a designated blob storage. 
+
+- Create a new YAML pipeline with the Starter pipeline template.
+- Add a PowerShell task to:
+  - Install [PSDocs.Azure][module] module.
+  - Scan for Azure template file recursively in the templates/ directory.
+  - Generate a standard name of the markdown file. i.e. `<name>_<version>`.md
+  - Generate the markdown to a specific directory.
+- Add an [AzureFileCopy task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/deploy/azure-file-copy?view=azure-devops) to copy the generated markdown to an Azure Storage Blob container.
+
+For example:
+
+```yaml
+# Example: .azure-pipelines/psdocs-blobstorage.yaml
+
+jobs:
+- job: 'generate_arm_template_documentation'
+  displayName: 'Generate ARM template docs'
+  pool:
+    vmImage: 'windows-2019'
+  steps:
+  # STEP 1: Generate Markdowns using PSDocs
+  - powershell: | 
+      Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -force;
+        # Scan for Azure template file recursively in the templates/ directory
+        Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
+        # Generate a standard name of the markdown file. i.e. <name>_<version>.md
+        $template = Get-Item -Path $_.TemplateFile;
+        $templateName = $template.Directory.Parent.Name;
+        $version = $template.Directory.Name;
+        $docName = "$($templateName)_$version";
+        # Generate markdown
+        Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $template.FullName -InstanceName $docName;
+      }
+    displayName: 'Export template data'
+    
+  # STEP 2: Copy files to a storage account
+  - task: AzureFileCopy@4
+    displayName: 'Copy files to a storage account blob container'
+    inputs:
+      SourcePath: 'out/docs/*'
+      azureSubscription: 'psdocstest'
+      Destination: 'AzureBlob'
+      storage: '<storageaccountname>' 
+      ContainerName: 'ps-docs'
+```
+
+### Using with GitHub Actions
+
+The following example shows how to setup GitHub Actions to copy generated markdown files to an Azure blob storage account.
+
+- See [Creating a workflow file][create-workflow] to create an empty workflow file.
+- Add a PowerShell step to:
+  - Install [PSDocs.Azure][module] module.
+  - Scan for Azure template file recursively in the templates/ directory.
+  - Generate a standard name of the markdown file. i.e. `<name>_<version>`.md
+  - Generate the markdown to a specific directory.
+- Set the `STORAGEACCOUNTSECRET` action secret.
+- Use an [Azure Blob Storage Upload action](https://github.com/marketplace/actions/azure-blob-storage-upload) to copy the generated markdown to an Azure Storage Blob container.
+
+For example:
+
+```yaml
+# Example: .github/workflows/arm-docs.yaml
+
+name: Generate ARM templates docs
+on:
+  push:
+    branches: [ main ]
+jobs:
+  arm_docs:
+    name: Generate ARM template docs
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    # STEP 1: Generate Markdowns using PSDocs
+    - name: Generate ARM markdowns
+      run: | 
+        Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -force;
+        # Scan for Azure template file recursively in the templates/ directory
+        Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
+          # Generate a standard name of the markdown file. i.e. <name>_<version>.md
+          $template = Get-Item -Path $_.TemplateFile;
+          $templateName = $template.Directory.Parent.Name;
+          $version = $template.Directory.Name;
+          $docName = "$($templateName)_$version";
+          # Generate markdown
+          Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $template.FullName -InstanceName $docName;
+        }
+      shell: pwsh
+
+    # STEP 2: Copy files to a storage account
+    - name: Copy files to a storage account
+      uses: bacongobbler/azure-blob-storage-upload@v1.1.1
+      with:
+        connection_string: ${{ secrets.STORAGEACCOUNTSECRET }}
+        container_name: ps-docs
+        source_dir: 'out/docs/*'
+```
+
+
 ## Changes and versioning
 
 Modules in this repository will use the [semantic versioning](http://semver.org/) model to declare breaking changes from v1.0.0.
@@ -198,3 +303,4 @@ This project is [licensed under the MIT License](LICENSE).
 [ci-badge]: https://dev.azure.com/PSDocs/PSDocs.Azure/_apis/build/status/PSDocs.Azure-CI?branchName=main
 [module]: https://www.powershellgallery.com/packages/PSDocs.Azure
 [engine]: https://github.com/BernieWhite/PSDocs
+[create-workflow]: https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file