diff --git a/README.md b/README.md index 0d1fa35..ffd742e 100644 --- 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. `_`.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. _.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: '' + 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. `_`.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. _.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