Added documentation generation for commands

.github/workflows/update-docs-cmdref.yaml

@@ -0,0 +1,41 @@
+# Regenerates the documentation for the "Command Reference" section of the site https://maester.dev
+#
+name: update-docs-cmdref
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Update docs
+        run: |
+          Import-Module ./src/Maester.psm1 -Force
+          New-DocusaurusHelp -Module Maester
+        shell: pwsh
+
+      - name: Update repo
+        run: |
+          if [[ `git status --porcelain` ]]; then
+            # Changes
+            echo "Updating command reference"
+            git config --global user.name 'Merill Fernando'
+            git config --global user.email 'merill@users.noreply.github.com'
+            git add -A && git commit -m "Bot: Updating command reference"
+            git push
+          else
+            # No changes
+            echo "No changes"
+          fi

.vscode/settings.json

@@ -1,10 +1,11 @@
 {
-    "editor.formatOnSave": true,
-    "powershell.codeFormatting.autoCorrectAliases": true,
-    "powershell.codeFormatting.avoidSemicolonsAsLineTerminators": true,
-    "powershell.codeFormatting.newLineAfterCloseBrace": false,
-    "powershell.codeFormatting.trimWhitespaceAroundPipe": true,
-    "powershell.codeFormatting.whitespaceBetweenParameters": true,
-    "powershell.analyzeOpenDocumentsOnly": false,
-    "files.trimTrailingWhitespace": true
-}
+  "editor.formatOnSave": true,
+  "powershell.codeFormatting.autoCorrectAliases": true,
+  "powershell.codeFormatting.avoidSemicolonsAsLineTerminators": true,
+  "powershell.codeFormatting.newLineAfterCloseBrace": false,
+  "powershell.codeFormatting.trimWhitespaceAroundPipe": true,
+  "powershell.codeFormatting.whitespaceBetweenParameters": true,
+  "powershell.analyzeOpenDocumentsOnly": false,
+  "files.trimTrailingWhitespace": true,
+  "cSpell.words": ["Maester"]
+}

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to Pester
+
+Thanks for taking the time to contribute! We welcome and encourage contributions to this project.
+
+Please read the the [Contributing](https://maester.dev/docs/contributing) Guide for details on how to contribute new commands and tests to Maester.
+
+## Documentation
+
+Documentation is available in the repo, and at <https://maester.dev>
+
+Documentation is written in Markdown. Comment-based Documentation and parts of the documentation web site are generated using [Docusaurus.Powershell](https://github.com/alt3/Docusaurus.Powershell).
+
+Multi-line examples added to comments should use fenced code.
+
+<https://docusaurus-powershell.vercel.app/docs/faq/multi-line-examples>

README.md

@@ -3,3 +3,7 @@
 Maester is a testing framework that helps you define and run tests on your Microsoft 365 cloud configuration.
 
 Please see the site https://maester.dev for all documentation related to this project.
+
+## Contributing
+
+Please see the [contributing guide](CONTRIBUTING.md) for details on how to contribute to this project.

build/Build-CommandReference.ps1

@@ -0,0 +1,12 @@
+# Description: This script is used to generate the 'Command Reference' section of the Maester docusaurus site
+# * This command needs to be run from the root of the project. e.g. ./build/Build-CommandReference.ps1
+# * The New-DocusaurusHelp command deletes and recreates the ./docs/docs/commands folder
+# * The Copy-Item command copies the ./docs/docs-templates/commands-index.md file to ./docs/docs/commands/index.md
+# * If running the docusaurus site locally you will need to stop and start Docusaurus to clear the 'Module not found' errors after running this command
+
+if (-not (Get-Module Alt3.Docusaurus.Powershell -ListAvailable)) {
+    Install-Module Alt3.Docusaurus.Powershell -Scope CurrentUser -Force -SkipPublisherCheck
+}
+Import-Module Alt3.Docusaurus.Powershell
+New-DocusaurusHelp -Module ./src/Maester.psm1 -DocsFolder ./docs/docs -NoPlaceHolderExamples
+Copy-Item ./docs/docs-templates/commands-index.md ./docs/docs/commands/index.md

docs/docs-templates/commands-index.md

@@ -0,0 +1,19 @@
+---
+id: commands
+title: Maester - Command Reference
+sidebar_label: Command Reference
+---
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+# Maester - Command Reference
+
+## Overview
+This page lists the commands available in the Maester module and provides a reference of the helper methods that have been created to help you define and run tests on your Microsoft 365 cloud configuration.
+
+See the [writing Maester tests](../writing-tests.md) guide for more information on how to write your own tests using these commands.
+
+## Maester Commands
+<DocCardList />
+```

docs/docs-templates/readme.md

@@ -0,0 +1 @@
+This folder contains markdown file templates that are used in the build process for documentation.

docs/docs/automation/azure-devops.md

@@ -0,0 +1,24 @@
+---
+sidebar_label: Azure DevOps
+sidebar_position: 1
+title: Azure DevOps
+---
+
+# <IIcon icon="vscode-icons:file-type-azurepipelines" height="48" /> Configure Maester in Azure DevOps
+
+## Set up the Maester repository in Azure DevOps
+
+### Setting up Maester in a new Azure DevOps project
+
+- If this is your first time using Azure DevOps, follow the steps in the [Azure DevOps - Create an organization](https://learn.microsoft.com/azure/devops/organizations/accounts/create-organization) to create an organization.
+- Create a new project for Maester in Azure DevOps by following the steps in the [Azure DevOps - Create a project](https://learn.microsoft.com/azure/devops/organizations/projects/create-project) guide.
+- Select **Repos** from the left-hand menu
+- Click the **Import** button in the **Import a repository** section
+- Enter the URL of the Maester repository `https://github.com/maester365/maester-tests.git`
+- Click **Import** to import the repository into your Azure DevOps project.
+
+### Setting up Maester in an existing Azure DevOps repository
+
+- If you would like to add Maester to an existing Azure DevOps repository you can clone `https://github.com/maester365/maester-tests.git` and copy the `tests` folder into your repository.
+
+## Using a Service Principal and secret

docs/docs/automation/index.mdx

@@ -0,0 +1,15 @@
+---
+id: automation
+title: Set up Maester to automatically run daily
+sidebar_label: Daily Automation
+sidebar_position: 3
+---
+
+This section provides guidance on how to set up Maester to be run as a daily automation.
+
+You can use any of the following methods to run Maester as a daily automation:
+
+- <IIcon icon="vscode-icons:file-type-azurepipelines" height="16" /> [Azure DevOps Pipeline](./azure-devops)
+- <IIcon icon="mdi:github" height="16" /> [GitHub Actions - TODO](./github-actions)
+- <IIcon icon="devicon:azure" height="16" /> [Azure Automation - TODO](./azure-automation)
+- <IIcon icon="logos:octopus-deploy" height="16" /> [Octopus Deploy - TODO](./octopus-deploy)

docs/docs/commands/Clear-MtGraphCache.mdx

@@ -0,0 +1,33 @@
+---
+id: Clear-MtGraphCache
+title: Clear-MtGraphCache
+hide_title: false
+hide_table_of_contents: false
+---
+
+## SYNOPSIS
+
+Resets the local cache of Graph API calls.
+Use this if you need to force a refresh of the cache in the current session.
+
+## SYNTAX
+
+```powershell
+Clear-MtGraphCache
+```
+
+## DESCRIPTION
+
+\{\{ Fill in the Description \}\}
+
+## EXAMPLES
+
+## PARAMETERS
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

docs/docs/commands/Export-MtHtmlReport.mdx

@@ -0,0 +1,93 @@
+---
+id: Export-MtHtmlReport
+title: Export-MtHtmlReport
+hide_title: false
+hide_table_of_contents: false
+---
+
+## SYNOPSIS
+
+Generates a formatted html report using the xml output from unit test frameworks like Pester.
+
+## SYNTAX
+
+```powershell
+Export-MtHtmlReport [-PesterResults] <PSObject> [-OutputHtmlPath] <String> [-ProgressAction <ActionPreference>]
+ [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+The generated html is a single file that provides a visual representation of the test
+results with a summary view and click through of the details.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```powershell
+$pesterResults = Invoke-Pester -PassThru
+Export-MtHtmlReport -PesterResults $pesterResults -OutputHtmlPath ./testResults.html
+```
+
+## PARAMETERS
+
+### -PesterResults
+
+The Pester test results returned from Invoke-Pester -PassThru
+
+```yaml
+Type: PSObject
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -OutputHtmlPath
+
+The path to the html file to be generated
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 2
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -ProgressAction
+
+\{\{ Fill ProgressAction Description \}\}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

docs/docs/commands/Get-MtConditionalAccessPolicies.mdx

@@ -0,0 +1,58 @@
+---
+id: Get-MtConditionalAccessPolicies
+title: Get-MtConditionalAccessPolicies
+hide_title: false
+hide_table_of_contents: false
+---
+
+## SYNOPSIS
+
+Returns all the conditional access policies in the tenant.
+
+## SYNTAX
+
+```powershell
+Get-MtConditionalAccessPolicies [-ProgressAction <ActionPreference>] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+\{\{ Fill in the Description \}\}
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```powershell
+Get-MtConditionalAccessPolicies
+```
+
+## PARAMETERS
+
+### -ProgressAction
+
+\{\{ Fill ProgressAction Description \}\}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS