├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── bug_report.md │ ├── feature_request.md │ └── question.md ├── PULL_REQUEST_TEMPLATE.md ├── dependabot.yml └── workflows │ └── build.yaml ├── .gitignore ├── .markdownlint.json ├── .vscode ├── extensions.json └── settings.json ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── Dockerfile ├── LICENSE ├── README.md ├── SECURITY.md ├── SUPPORT.md ├── action.yml ├── docs └── CHANGELOG-v0.md ├── powershell.ps1 ├── ps-project.yaml └── ps-rule.yaml /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # https://help.github.com/articles/about-codeowners/ 2 | * @microsoft/psdocs 3 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Report errors or an unexpected issue 4 | labels: bug 5 | --- 6 | 7 | **Description of the issue** 8 | 9 | 10 | 11 | **Expected behaviour** 12 | 13 | 14 | 15 | **To Reproduce** 16 | 17 | Steps to reproduce the issue: 18 | 19 | ```yaml 20 | 21 | ``` 22 | 23 | **Error output** 24 | 25 | 26 | 27 | ```text 28 | 29 | ``` 30 | 31 | **Action version:** 32 | 33 | - Version: **[e.g. 0.1.0]** 34 | 35 | **Additional context** 36 | 37 | 38 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea 4 | labels: enhancement 5 | --- 6 | 7 | **Is your feature request related to a problem? Please describe.** 8 | 9 | 10 | 11 | **Describe the solution you'd like** 12 | 13 | 14 | 15 | **Describe alternatives you've considered** 16 | 17 | 18 | 19 | **Additional context** 20 | 21 | 22 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/question.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Question 3 | about: If you have a question, please check out Discussions 4 | labels: 'question' 5 | --- 6 | 7 | We use Issues as an issue tracker; for help, discussion, and support questions, please use Discussions. 8 | 9 | Thanks! 😁. 10 | 11 | - https://github.com/microsoft/ps-docs/discussions 12 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ## PR Summary 2 | 3 | 4 | 5 | ## PR Checklist 6 | 7 | - [ ] PR has a meaningful title 8 | - [ ] Summarized changes 9 | - [ ] Change is not breaking 10 | - [ ] This PR is ready to merge and is not **Work in Progress** 11 | - **Code changes** 12 | - [ ] Have unit tests created/ updated 13 | - [ ] Link to a filed issue 14 | - [ ] [Change log](https://github.com/Microsoft/ps-docs/blob/main/docs/CHANGELOG-v0.md) has been updated with change under unreleased section 15 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # 2 | # Dependabot configuration 3 | # 4 | 5 | # Please see the documentation for all configuration options: 6 | # https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 7 | 8 | version: 2 9 | updates: 10 | 11 | # Maintain dependencies for GitHub Actions 12 | - package-ecosystem: 'github-actions' 13 | directory: '/' 14 | schedule: 15 | interval: 'daily' 16 | labels: 17 | - 'dependencies' 18 | reviewers: 19 | - '@microsoft/psdocs' 20 | 21 | # Maintain dependencies for Docker 22 | - package-ecosystem: 'docker' 23 | directory: '/' 24 | schedule: 25 | interval: 'daily' 26 | labels: 27 | - 'dependencies' 28 | reviewers: 29 | - '@microsoft/psdocs' 30 | -------------------------------------------------------------------------------- /.github/workflows/build.yaml: -------------------------------------------------------------------------------- 1 | # 2 | # Repository validation 3 | # 4 | name: Analyze 5 | on: 6 | - pull_request 7 | 8 | jobs: 9 | analyze: 10 | name: Analyze repository 11 | runs-on: ubuntu-latest 12 | steps: 13 | 14 | - name: Checkout 15 | uses: actions/checkout@main 16 | 17 | - name: Run PSRule analysis 18 | uses: Microsoft/ps-rule@main 19 | with: 20 | modules: PSRule.Rules.MSFT.OSS 21 | prerelease: true 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | out/ 3 | reports/ 4 | -------------------------------------------------------------------------------- /.markdownlint.json: -------------------------------------------------------------------------------- 1 | { 2 | "default": true, 3 | "header-increment": true, 4 | "first-header-h1": { 5 | "level": 1 6 | }, 7 | "header-style": { 8 | "style": "atx" 9 | }, 10 | "ul-style": { 11 | "style": "dash" 12 | }, 13 | "list-indent": true, 14 | "ul-start-left": true, 15 | "ul-indent": { 16 | "indent": 2 17 | }, 18 | "no-trailing-spaces": true, 19 | "no-hard-tabs": true, 20 | "no-reversed-links": true, 21 | "no-multiple-blanks": true, 22 | "line-length": { 23 | "line_length": 100, 24 | "code_blocks": false, 25 | "tables": false, 26 | "headers": true 27 | }, 28 | "commands-show-output": true, 29 | "no-missing-space-atx": true, 30 | "no-multiple-space-atx": true, 31 | "no-missing-space-closed-atx": true, 32 | "no-multiple-space-closed-atx": true, 33 | "blanks-around-headers": true, 34 | "header-start-left": true, 35 | "no-duplicate-header": true, 36 | "single-h1": true, 37 | "no-trailing-punctuation": { 38 | "punctuation": ".,;:!" 39 | }, 40 | "no-multiple-space-blockquote": true, 41 | "no-blanks-blockquote": true, 42 | "ol-prefix": { 43 | "style": "one_or_ordered" 44 | }, 45 | "list-marker-space": true, 46 | "blanks-around-fences": true, 47 | "blanks-around-lists": true, 48 | "no-bare-urls": true, 49 | "hr-style": { 50 | "style": "---" 51 | }, 52 | "no-emphasis-as-header": true, 53 | "no-space-in-emphasis": true, 54 | "no-space-in-code": true, 55 | "no-space-in-links": true, 56 | "fenced-code-language": false, 57 | "first-line-h1": false, 58 | "no-empty-links": true, 59 | "proper-names": { 60 | "names": [ 61 | "PowerShell", 62 | "JavaScript" 63 | ], 64 | "code_blocks": false 65 | }, 66 | "no-alt-text": true 67 | } 68 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": [ 3 | "github.vscode-pull-request-github", 4 | "ms-vscode.powershell", 5 | "davidanson.vscode-markdownlint", 6 | "redhat.vscode-yaml", 7 | "streetsidesoftware.code-spell-checker" 8 | ] 9 | } 10 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "files.exclude": { 3 | "reports/": true, 4 | "out/": true, 5 | ".vs/": true 6 | }, 7 | "search.exclude": { 8 | "out/": true 9 | }, 10 | "editor.insertSpaces": true, 11 | "editor.tabSize": 4, 12 | "[yaml]": { 13 | "editor.tabSize": 2 14 | }, 15 | "[markdown]": { 16 | "editor.tabSize": 2 17 | } 18 | } -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Change log 2 | 3 | ## Current release 4 | 5 | - [v0](docs/CHANGELOG-v0.md) 6 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Microsoft Open Source Code of Conduct 2 | 3 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 4 | 5 | Resources: 6 | 7 | - [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) 8 | - [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 9 | - Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns 10 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | This project welcomes contributions and suggestions. Most contributions require you to 4 | agree to a Contributor License Agreement (CLA) declaring that you have the right to, 5 | and actually do, grant us the rights to use your contribution. For details, visit 6 | https://cla.microsoft.com. 7 | 8 | When you submit a pull request, a CLA-bot will automatically determine whether you need 9 | to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the 10 | instructions provided by the bot. You will only need to do this once across all repositories using our CLA. 11 | 12 | ## Code of Conduct 13 | 14 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 15 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 16 | or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 17 | 18 | ## How to contribute 19 | 20 | - File or vote up issues 21 | - Improve documentation 22 | - Fix bugs or add features 23 | 24 | ### Intro to Git and GitHub 25 | 26 | When contributing to documentation or code changes, you'll need to have a GitHub account and a basic understanding of Git. 27 | Check out the links below to get started. 28 | 29 | - Make sure you have a [GitHub account][github-signup]. 30 | - GitHub Help: 31 | - [Git and GitHub learning resources][learn-git]. 32 | - [GitHub Flow Guide][github-flow]. 33 | - [Fork a repo][github-fork]. 34 | - [About Pull Requests][github-pr]. 35 | 36 | ## Contributing to issues 37 | 38 | - Check if the issue you are going to file already exists in our GitHub [issues](https://github.com/Microsoft/ps-docs/issues). 39 | - If you do not see your problem captured, please file a new issue and follow the provided template. 40 | - If the an open issue exists for the problem you are experiencing, vote up the issue or add a comment. 41 | 42 | ## Contributing to code 43 | 44 | - Before writing a fix or feature enhancement, ensure that an issue is logged. 45 | - Be prepared to discuss a feature and take feedback. 46 | - Include unit tests and updates documentation to complement the change. 47 | 48 | [learn-git]: https://help.github.com/en/articles/git-and-github-learning-resources 49 | [github-flow]: https://guides.github.com/introduction/flow/ 50 | [github-signup]: https://github.com/signup/free 51 | [github-fork]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo 52 | [github-pr]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests 53 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | # Copyright (c) Microsoft Corporation. 2 | # Licensed under the MIT License. 3 | 4 | ARG MODULE_VERSION=0.9.0 5 | 6 | FROM mcr.microsoft.com/powershell:7.1.3-alpine-3.12-20210803 7 | SHELL ["pwsh", "-Command"] 8 | RUN $ProgressPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue; \ 9 | $Null = New-Item -Path /ps_modules/ -ItemType Directory -Force; \ 10 | Save-Module -Name PSDocs -RequiredVersion ${MODULE_VERSION} -Force -Path /ps_modules/; 11 | 12 | COPY LICENSE README.md powershell.ps1 / 13 | CMD ["pwsh", "-File", "/powershell.ps1"] 14 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Microsoft Corporation. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # PSDocs 2 | 3 | Generate documentation from Infrastructure as Code (IaC) using PSDocs. 4 | PSDocs allows you to dynamically generate markdown from infrastructure code artifacts. 5 | Use pre-build modules or build your own. 6 | 7 | To learn about PSDocs and how you can build documentation dynamically see [Getting started](https://github.com/microsoft/PSDocs#getting-started). 8 | 9 | ## Usage 10 | 11 | To get the latest stable release use: 12 | 13 | ```yaml 14 | - name: Generate docs 15 | uses: Microsoft/ps-docs@v0.1.0 16 | ``` 17 | 18 | To get the latest bits use: 19 | 20 | ```yaml 21 | - name: Generate docs 22 | uses: Microsoft/ps-docs@main 23 | ``` 24 | 25 | For a list of changes please see the [change log]. 26 | 27 | ## Inputs 28 | 29 | ```yaml 30 | - name: Generate docs 31 | uses: Microsoft/ps-docs@main 32 | with: 33 | inputPath: string # Optional. The path PSDocs will look for files to input files. 34 | modules: string # Optional. A comma separated list of modules to use containing document definitions. 35 | source: string # Optional. An path containing definitions to use for generating documentation. 36 | conventions: string # Optional. A comma separated list of conventions to use for generating documentation. 37 | outputPath: string # Optional. The path to write documentation to. 38 | path: string # Optional. The working directory PSDocs is run from. 39 | prerelease: boolean # Optional. Determine if a pre-release module version is installed. 40 | ``` 41 | 42 | ### `inputPath` 43 | 44 | The path PSDocs will look for files to input files. 45 | Defaults to repository root. 46 | 47 | ### `modules` 48 | 49 | A comma separated list of modules to use containing document definitions. 50 | 51 | Modules are additional packages that can be installed from the PowerShell Gallery. 52 | PSDocs will install the latest **stable** version from the PowerShell Gallery automatically by default. 53 | [Available modules](https://www.powershellgallery.com/packages?q=Tags%3A%22PSDocs-documents%22). 54 | 55 | To install pre-release module versions, use `prerelease: true`. 56 | 57 | ### `source` 58 | 59 | An path containing definitions to use for generating documentation. 60 | Defaults to `.ps-docs/`. 61 | 62 | Use this option to include document definitions that have not been packaged as a module. 63 | 64 | ### `conventions` 65 | 66 | A comma separated list of conventions to use for generating documentation. 67 | 68 | Conventions are code blocks that provide extensibility and integration. 69 | They can be included in `.Doc.ps1` files from `.ps-docs/` or modules. 70 | 71 | See [about_PSDocs_Conventions][2] for more information. 72 | 73 | [2]: https://github.com/microsoft/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Conventions.md 74 | 75 | ### `outputPath` 76 | 77 | The path to write documentation to. 78 | 79 | ### `path` 80 | 81 | The working directory PSDocs is run from. 82 | Defaults to repository root. 83 | 84 | Options specified in `ps-docs.yaml` from this directory will be used unless overridden by inputs. 85 | 86 | ### `prerelease` 87 | 88 | Determine if a pre-release rules module version is installed. 89 | When set to `true` the latest pre-release or stable module version is installed. 90 | 91 | If this input is not configured, invalid, or set to `false` only stable module versions will be installed. 92 | 93 | ## Using the action 94 | 95 | To use PSDocs: 96 | 97 | 1. See [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file). 98 | 2. Reference `Microsoft/ps-docs@main`. 99 | For example: 100 | 101 | ```yaml 102 | name: CI 103 | on: [push] 104 | jobs: 105 | docs: 106 | runs-on: ubuntu-latest 107 | steps: 108 | 109 | - name: Checkout 110 | uses: actions/checkout@main 111 | 112 | - name: Generate docs 113 | uses: Microsoft/ps-docs@main 114 | ``` 115 | 116 | 3. Run the workflow. 117 | 118 | ## Contributing 119 | 120 | This project welcomes contributions and suggestions. Most contributions require you to 121 | agree to a Contributor License Agreement (CLA) declaring that you have the right to, 122 | and actually do, grant us the rights to use your contribution. For details, visit 123 | https://cla.microsoft.com. 124 | 125 | When you submit a pull request, a CLA-bot will automatically determine whether you need 126 | to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the 127 | instructions provided by the bot. You will only need to do this once across all repositories using our CLA. 128 | 129 | ## Code of Conduct 130 | 131 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 132 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 133 | or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 134 | 135 | ## Maintainers 136 | 137 | - [Bernie White](https://github.com/BernieWhite) 138 | - [Vic Perdana](https://github.com/vicperdana) 139 | 140 | ## License 141 | 142 | This project is [licensed under the MIT License](LICENSE). 143 | 144 | [change log]: CHANGELOG.md 145 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security policy 2 | 3 | 4 | 5 | ## Security 6 | 7 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 8 | 9 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)) of a security vulnerability, please report it to us as described below. 10 | 11 | ## Reporting Security Issues 12 | 13 | **Please do not report security vulnerabilities through public GitHub issues.** 14 | 15 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). 16 | 17 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). 18 | 19 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 20 | 21 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 22 | 23 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 24 | * Full paths of source file(s) related to the manifestation of the issue 25 | * The location of the affected source code (tag/branch/commit or direct URL) 26 | * Any special configuration required to reproduce the issue 27 | * Step-by-step instructions to reproduce the issue 28 | * Proof-of-concept or exploit code (if possible) 29 | * Impact of the issue, including how an attacker might exploit the issue 30 | 31 | This information will help us triage your report more quickly. 32 | 33 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://microsoft.com/msrc/bounty) page for more details about our active programs. 34 | 35 | ## Preferred Languages 36 | 37 | We prefer all communications to be in English. 38 | 39 | ## Policy 40 | 41 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). 42 | 43 | 44 | -------------------------------------------------------------------------------- /SUPPORT.md: -------------------------------------------------------------------------------- 1 | # Support 2 | 3 | ## How to file issues and get help 4 | 5 | This project uses GitHub Issues to track bugs and feature requests. 6 | Please search the existing issues before filing new issues to avoid duplicates. 7 | 8 | - For new issues, file your bug or feature request as a new [issue]. 9 | - For help, discussion, and support questions about using this project, join or start a [discussion]. 10 | 11 | ## Microsoft Support Policy 12 | 13 | Support for this project/ product is limited to the resources listed above. 14 | 15 | [issue]: https://github.com/microsoft/ps-docs/issues 16 | [discussion]: https://github.com/microsoft/ps-docs/discussions 17 | -------------------------------------------------------------------------------- /action.yml: -------------------------------------------------------------------------------- 1 | name: 'ps-docs' 2 | description: 'Generate documentation from Infrastructure as Code (IaC) using GitHub Actions.' 3 | author: 'Microsoft' 4 | branding: 5 | icon: 'book-open' 6 | color: 'blue' 7 | inputs: 8 | 9 | inputPath: 10 | description: 'The path PSDocs will look for files to input files.' 11 | default: '' 12 | required: false 13 | 14 | modules: 15 | description: 'A comma separated list of modules to use containing document definitions.' 16 | default: '' 17 | required: false 18 | 19 | source: 20 | description: 'An path containing definitions to use for generating documentation.' 21 | default: '.ps-docs/' 22 | required: false 23 | 24 | conventions: 25 | description: 'A comma separated list of conventions to use for generating documentation.' 26 | default: '' 27 | required: false 28 | 29 | outputPath: 30 | description: 'The path to write documentation to.' 31 | default: '' 32 | required: false 33 | 34 | path: 35 | description: 'The working directory PSDocs is run from.' 36 | default: '' 37 | required: false 38 | 39 | prerelease: 40 | description: 'Determine if a pre-release module version is installed.' 41 | default: 'false' 42 | required: false 43 | 44 | runs: 45 | using: 'docker' 46 | image: 'Dockerfile' 47 | -------------------------------------------------------------------------------- /docs/CHANGELOG-v0.md: -------------------------------------------------------------------------------- 1 | # Change log 2 | 3 | ## v0.1.0 4 | 5 | - Initial release. 6 | -------------------------------------------------------------------------------- /powershell.ps1: -------------------------------------------------------------------------------- 1 | # Copyright (c) Microsoft Corporation. 2 | # Licensed under the MIT License. 3 | 4 | # 5 | # PSDocs 6 | # 7 | 8 | # See details at: https://github.com/Microsoft/ps-docs 9 | 10 | [CmdletBinding()] 11 | param ( 12 | # The working directory PSDocs is run from. 13 | [Parameter(Mandatory = $False)] 14 | [String]$Path = $Env:INPUT_PATH, 15 | 16 | # The path PSDocs will look for files to input files. 17 | [Parameter(Mandatory = $False)] 18 | [String]$InputPath = $Env:INPUT_INPUTPATH, 19 | 20 | # An path containing definitions to use for generating documentation. 21 | [Parameter(Mandatory = $False)] 22 | [String]$Source = $Env:INPUT_SOURCE, 23 | 24 | # A comma separated list of modules to use containing document definitions. 25 | [Parameter(Mandatory = $False)] 26 | [String]$Modules = $Env:INPUT_MODULES, 27 | 28 | [Parameter(Mandatory = $False)] 29 | [String]$Conventions = $ENV:INPUT_CONVENTIONS, 30 | 31 | # The path to write documentation to. 32 | [Parameter(Mandatory = $False)] 33 | [String]$OutputPath = $Env:INPUT_OUTPUTPATH, 34 | 35 | # Determine if a pre-release module version is installed. 36 | [Parameter(Mandatory = $False)] 37 | [String]$PreRelease = $Env:INPUT_PRERELEASE 38 | ) 39 | 40 | $workspacePath = $Env:GITHUB_WORKSPACE; 41 | $ProgressPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue; 42 | if ($Env:SYSTEM_DEBUG -eq 'true') { 43 | $VerbosePreference = [System.Management.Automation.ActionPreference]::Continue; 44 | } 45 | 46 | # Set workspace 47 | if ([String]::IsNullOrEmpty($workspacePath)) { 48 | $workspacePath = $PWD; 49 | } 50 | 51 | # Set Path 52 | if ([String]::IsNullOrEmpty($Path)) { 53 | $Path = $workspacePath; 54 | } 55 | else { 56 | $Path = Join-Path -Path $workspacePath -ChildPath $Path; 57 | } 58 | 59 | # Set InputPath 60 | if ([String]::IsNullOrEmpty($InputPath)) { 61 | $InputPath = $Path; 62 | } 63 | else { 64 | $InputPath = Join-Path -Path $Path -ChildPath $InputPath; 65 | } 66 | 67 | # Set Source 68 | if ([String]::IsNullOrEmpty($Source)) { 69 | $Source = Join-Path -Path $Path -ChildPath '.ps-docs/'; 70 | } 71 | else { 72 | $Source = Join-Path -Path $Path -ChildPath $Source; 73 | } 74 | 75 | function WriteDebug { 76 | [CmdletBinding()] 77 | param ( 78 | [Parameter(Position = 0, Mandatory = $True)] 79 | [String]$Message 80 | ) 81 | process { 82 | if ($Env:SYSTEM_DEBUG -eq 'true' -or $Env:ACTIONS_STEP_DEBUG -eq 'true') { 83 | Write-Host "::debug::$Message"; 84 | } 85 | } 86 | } 87 | 88 | # Setup paths for importing modules 89 | $modulesPath = '/ps_modules/'; 90 | if ((Get-Variable -Name IsMacOS -ErrorAction Ignore) -or (Get-Variable -Name IsLinux -ErrorAction Ignore)) { 91 | $moduleSearchPaths = $Env:PSModulePath.Split(':', [System.StringSplitOptions]::RemoveEmptyEntries); 92 | if ($modulesPath -notin $moduleSearchPaths) { 93 | $Env:PSModulePath += [String]::Concat($Env:PSModulePath, ':', $modulesPath); 94 | } 95 | } 96 | else { 97 | $moduleSearchPaths = $Env:PSModulePath.Split(';', [System.StringSplitOptions]::RemoveEmptyEntries); 98 | if ($modulesPath -notin $moduleSearchPaths) { 99 | $Env:PSModulePath += [String]::Concat($Env:PSModulePath, ';', $modulesPath); 100 | } 101 | } 102 | 103 | $moduleNames = @() 104 | if (![String]::IsNullOrEmpty($Modules)) { 105 | $moduleNames = $Modules.Split(',', [System.StringSplitOptions]::RemoveEmptyEntries); 106 | } 107 | $moduleParams = @{ 108 | Scope = 'CurrentUser' 109 | Force = $True 110 | } 111 | if ($PreRelease -eq 'true') { 112 | $moduleParams['AllowPrerelease'] = $True; 113 | } 114 | 115 | try { 116 | # Install each module if not already installed 117 | foreach ($m in $moduleNames) { 118 | $m = $m.Trim(); 119 | Write-Host "> Checking module: $m"; 120 | if ($Null -eq (Get-InstalledModule -Name $m -ErrorAction Ignore)) { 121 | Write-Host ' - Installing module'; 122 | $Null = Install-Module -Name $m @moduleParams -AllowClobber -ErrorAction Stop; 123 | } 124 | else { 125 | Write-Host ' - Already installed'; 126 | } 127 | # Check 128 | if ($Null -eq (Get-InstalledModule -Name $m)) { 129 | Write-Host "::error::Failed to install $m."; 130 | } 131 | else { 132 | Write-Host " - Using version: $((Get-InstalledModule -Name $m).Version)"; 133 | } 134 | } 135 | } 136 | catch { 137 | Write-Host "::error::An error occured installing a dependency module."; 138 | $Host.SetShouldExit(1); 139 | } 140 | 141 | $Null = Import-Module PSDocs -ErrorAction Stop; 142 | $version = (Get-InstalledModule PSDocs).Version; 143 | 144 | Write-Host ''; 145 | Write-Host "[info] Using Version: $version"; 146 | Write-Host "[info] Using Action: $Env:GITHUB_ACTION"; 147 | Write-Host "[info] Using PWD: $PWD"; 148 | Write-Host "[info] Using Path: $Path"; 149 | Write-Host "[info] Using Source: $Source"; 150 | Write-Host "[info] Using Conventions: $Conventions"; 151 | Write-Host "[info] Using InputPath: $InputPath"; 152 | Write-Host "[info] Using OutputPath: $OutputPath"; 153 | 154 | try { 155 | Push-Location -Path $Path; 156 | $invokeParams = @{ 157 | Path = $Source 158 | ErrorAction = 'Stop' 159 | } 160 | WriteDebug "Preparing command-line:"; 161 | WriteDebug ([String]::Concat('-Path ''', $Source, '''')); 162 | if (![String]::IsNullOrEmpty($Modules)) { 163 | $moduleNames = $Modules.Split(',', [System.StringSplitOptions]::RemoveEmptyEntries); 164 | $invokeParams['Module'] = $moduleNames; 165 | WriteDebug ([String]::Concat('-Module ', [String]::Join(', ', $moduleNames))); 166 | } 167 | if (![String]::IsNullOrEmpty($Conventions)) { 168 | $conventionNames = $Conventions.Split(',', [System.StringSplitOptions]::RemoveEmptyEntries); 169 | $invokeParams['Convention'] = $conventionNames; 170 | WriteDebug ([String]::Concat('-Convention ', [String]::Join(', ', $conventionNames))); 171 | } 172 | if (![String]::IsNullOrEmpty($OutputPath)) { 173 | $invokeParams['OutputPath'] = $OutputPath; 174 | WriteDebug ([String]::Concat('-OutputPath ''', $OutputPath, '''')); 175 | } 176 | 177 | WriteDebug 'Running ''Invoke-PSDocument''.'; 178 | Write-Host ''; 179 | Write-Host '---'; 180 | Invoke-PSDocument @invokeParams -InputPath $InputPath; 181 | } 182 | catch { 183 | Write-Host "::error::An error occured generating documentation. $($_.Exception.Message)"; 184 | if ($Null -ne $_.ScriptStackTrace) { 185 | $_.ScriptStackTrace; 186 | } 187 | $Host.SetShouldExit(1); 188 | } 189 | finally { 190 | Pop-Location; 191 | } 192 | Write-Host '---'; 193 | -------------------------------------------------------------------------------- /ps-project.yaml: -------------------------------------------------------------------------------- 1 | 2 | info: 3 | name: PSDocs 4 | description: Generate documentation from Infrastructure as Code (IaC) using GitHub Actions. 5 | url: https://github.com/Microsoft/ps-docs 6 | 7 | repository: 8 | type: git 9 | url: https://github.com/Microsoft/ps-docs.git 10 | 11 | license: MIT 12 | 13 | bugs: 14 | url: https://github.com/Microsoft/ps-docs/issues 15 | 16 | # modules: 17 | # PSDocs: '@pre >=0.9.0' 18 | 19 | tasks: 20 | clear: 21 | steps: 22 | - gitPrune: 23 | name: origin 24 | removeGone: true 25 | -------------------------------------------------------------------------------- /ps-rule.yaml: -------------------------------------------------------------------------------- 1 | # 2 | # PSRule configuration 3 | # 4 | 5 | # Please see the documentation for all configuration options: 6 | # https://microsoft.github.io/PSRule/ 7 | 8 | requires: 9 | PSRule: '@pre >=1.4.0' 10 | 11 | output: 12 | culture: 13 | - en-US 14 | 15 | input: 16 | pathIgnore: 17 | - '*.md' 18 | - '.vscode/' 19 | --------------------------------------------------------------------------------