diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..306144a --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# https://help.github.com/articles/about-codeowners/ +* @microsoft/psdocs diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..9a0df14 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,37 @@ +--- +name: Bug report +about: Report errors or an unexpected issue +labels: bug +--- + +**Description of the issue** + + + +**Expected behaviour** + + + +**To Reproduce** + +Steps to reproduce the issue: + +```yaml + +``` + +**Error output** + + + +```text + +``` + +**Action version:** + +- Version: **[e.g. 0.1.0]** + +**Additional context** + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b8c17f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,21 @@ +--- +name: Feature request +about: Suggest an idea +labels: enhancement +--- + +**Is your feature request related to a problem? Please describe.** + + + +**Describe the solution you'd like** + + + +**Describe alternatives you've considered** + + + +**Additional context** + + diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..bfacb45 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,11 @@ +--- +name: Question +about: If you have a question, please check out Discussions +labels: 'question' +--- + +We use Issues as an issue tracker; for help, discussion, and support questions, please use Discussions. + +Thanks! 😁. + +- https://github.com/microsoft/ps-docs/discussions diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..b432fa2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +## PR Summary + + + +## PR Checklist + +- [ ] PR has a meaningful title +- [ ] Summarized changes +- [ ] Change is not breaking +- [ ] This PR is ready to merge and is not **Work in Progress** +- **Code changes** + - [ ] Have unit tests created/ updated + - [ ] Link to a filed issue + - [ ] [Change log](https://github.com/Microsoft/ps-docs/blob/main/docs/CHANGELOG-v0.md) has been updated with change under unreleased section diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..182307a --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,29 @@ +# +# Dependabot configuration +# + +# Please see the documentation for all configuration options: +# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + + # Maintain dependencies for GitHub Actions + - package-ecosystem: 'github-actions' + directory: '/' + schedule: + interval: 'daily' + labels: + - 'dependencies' + reviewers: + - '@microsoft/psdocs' + + # Maintain dependencies for Docker + - package-ecosystem: 'docker' + directory: '/' + schedule: + interval: 'daily' + labels: + - 'dependencies' + reviewers: + - '@microsoft/psdocs' diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 0000000..07aa9d1 --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,21 @@ +# +# Repository validation +# +name: Analyze +on: +- pull_request + +jobs: + analyze: + name: Analyze repository + runs-on: ubuntu-latest + steps: + + - name: Checkout + uses: actions/checkout@main + + - name: Run PSRule analysis + uses: Microsoft/ps-rule@main + with: + modules: PSRule.Rules.MSFT.OSS + prerelease: true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c702f88 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ + +out/ +reports/ diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..243930f --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,67 @@ +{ + "default": true, + "header-increment": true, + "first-header-h1": { + "level": 1 + }, + "header-style": { + "style": "atx" + }, + "ul-style": { + "style": "dash" + }, + "list-indent": true, + "ul-start-left": true, + "ul-indent": { + "indent": 2 + }, + "no-trailing-spaces": true, + "no-hard-tabs": true, + "no-reversed-links": true, + "no-multiple-blanks": true, + "line-length": { + "line_length": 100, + "code_blocks": false, + "tables": false, + "headers": true + }, + "commands-show-output": true, + "no-missing-space-atx": true, + "no-multiple-space-atx": true, + "no-missing-space-closed-atx": true, + "no-multiple-space-closed-atx": true, + "blanks-around-headers": true, + "header-start-left": true, + "no-duplicate-header": true, + "single-h1": true, + "no-trailing-punctuation": { + "punctuation": ".,;:!" + }, + "no-multiple-space-blockquote": true, + "no-blanks-blockquote": true, + "ol-prefix": { + "style": "one_or_ordered" + }, + "list-marker-space": true, + "blanks-around-fences": true, + "blanks-around-lists": true, + "no-bare-urls": true, + "hr-style": { + "style": "---" + }, + "no-emphasis-as-header": true, + "no-space-in-emphasis": true, + "no-space-in-code": true, + "no-space-in-links": true, + "fenced-code-language": false, + "first-line-h1": false, + "no-empty-links": true, + "proper-names": { + "names": [ + "PowerShell", + "JavaScript" + ], + "code_blocks": false + }, + "no-alt-text": true +} diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..565e73d --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,9 @@ +{ + "recommendations": [ + "github.vscode-pull-request-github", + "ms-vscode.powershell", + "davidanson.vscode-markdownlint", + "redhat.vscode-yaml", + "streetsidesoftware.code-spell-checker" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..f8f574a --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,18 @@ +{ + "files.exclude": { + "reports/": true, + "out/": true, + ".vs/": true + }, + "search.exclude": { + "out/": true + }, + "editor.insertSpaces": true, + "editor.tabSize": 4, + "[yaml]": { + "editor.tabSize": 2 + }, + "[markdown]": { + "editor.tabSize": 2 + } +} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..26108d5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,5 @@ +# Change log + +## Current release + +- [v0](docs/CHANGELOG-v0.md) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dee4395 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing + +This project welcomes contributions and suggestions. Most contributions require you to +agree to a Contributor License Agreement (CLA) declaring that you have the right to, +and actually do, grant us the rights to use your contribution. For details, visit +https://cla.microsoft.com. + +When you submit a pull request, a CLA-bot will automatically determine whether you need +to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the +instructions provided by the bot. You will only need to do this once across all repositories using our CLA. + +## Code of Conduct + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## How to contribute + +- File or vote up issues +- Improve documentation +- Fix bugs or add features + +### Intro to Git and GitHub + +When contributing to documentation or code changes, you'll need to have a GitHub account and a basic understanding of Git. +Check out the links below to get started. + +- Make sure you have a [GitHub account][github-signup]. +- GitHub Help: + - [Git and GitHub learning resources][learn-git]. + - [GitHub Flow Guide][github-flow]. + - [Fork a repo][github-fork]. + - [About Pull Requests][github-pr]. + +## Contributing to issues + +- Check if the issue you are going to file already exists in our GitHub [issues](https://github.com/Microsoft/ps-docs/issues). +- If you do not see your problem captured, please file a new issue and follow the provided template. +- If the an open issue exists for the problem you are experiencing, vote up the issue or add a comment. + +## Contributing to code + +- Before writing a fix or feature enhancement, ensure that an issue is logged. +- Be prepared to discuss a feature and take feedback. +- Include unit tests and updates documentation to complement the change. + +[learn-git]: https://help.github.com/en/articles/git-and-github-learning-resources +[github-flow]: https://guides.github.com/introduction/flow/ +[github-signup]: https://github.com/signup/free +[github-fork]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo +[github-pr]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..2a39e2c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,15 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +ARG MODULE_VERSION=0.9.0 + +# NOTE: Use pre-release version with -AllowPrerelease. + +FROM mcr.microsoft.com/powershell:7.1.3-alpine-3.12-20210603 +SHELL ["pwsh", "-Command"] +RUN $ProgressPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue; \ + $Null = New-Item -Path /ps_modules/ -ItemType Directory -Force; \ + Save-Module -Name PSDocs -RequiredVersion ${MODULE_VERSION} -Force -Path /ps_modules/ -AllowPrerelease; + +COPY LICENSE README.md powershell.ps1 / +CMD ["pwsh", "-File", "/powershell.ps1"] diff --git a/LICENSE b/LICENSE index 9e841e7..22aed37 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,21 @@ - MIT License +MIT License - Copyright (c) Microsoft Corporation. +Copyright (c) Microsoft Corporation. - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 5cd7cec..712a36e 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,131 @@ -# Project +# PSDocs -> This repo has been populated by an initial template to help get you started. Please -> make sure to update the content to build a great experience for community-building. +Generate documentation from Infrastructure as Code (IaC) using PSDocs. +PSDocs allows you to dynamically generate markdown from infrastructure code artifacts. +Use pre-build modules or build your own. -As the maintainer of this project, please make a few updates: +To learn about PSDocs and how you can build documentation dynamically see [Getting started](https://github.com/microsoft/PSDocs#getting-started). -- Improving this README.MD file to provide a great experience -- Updating SUPPORT.MD with content about this project's support experience -- Understanding the security reporting process in SECURITY.MD -- Remove this section from the README +## Usage + + + +To get the latest bits use: + +```yaml +- name: Generate docs + uses: Microsoft/ps-docs@main +``` + +For a list of changes please see the [change log]. + +## Inputs + +```yaml +- name: Generate docs + uses: Microsoft/ps-docs@main + with: + inputPath: string # Optional. The path PSDocs will look for files to input files. + modules: string # Optional. A comma separated list of modules to use containing document definitions. + source: string # Optional. An path containing definitions to use for generating documentation. + outputPath: string # Optional. The path to write documentation to. + path: string # Optional. The working directory PSDocs is run from. + prerelease: boolean # Optional. Determine if a pre-release module version is installed. +``` + +### `inputPath` + +The path PSDocs will look for files to input files. +Defaults to repository root. + +### `modules` + +A comma separated list of modules to use containing document definitions. + +Modules are additional packages that can be installed from the PowerShell Gallery. +PSDocs will install the latest **stable** version from the PowerShell Gallery automatically by default. +[Available modules](https://www.powershellgallery.com/packages?q=Tags%3A%22PSDocs-documents%22). + +To install pre-release module versions, use `prerelease: true`. + +### `source` + +An path containing definitions to use for generating documentation. +Defaults to `.ps-docs/`. + +Use this option to include document definitions that have not been packaged as a module. + +### `outputPath` + +The path to write documentation to. + +### `path` + +The working directory PSDocs is run from. +Defaults to repository root. + +Options specified in `ps-docs.yaml` from this directory will be used unless overridden by inputs. + +### `prerelease` + +Determine if a pre-release rules module version is installed. +When set to `true` the latest pre-release or stable module version is installed. + +If this input is not configured, invalid, or set to `false` only stable module versions will be installed. + +## Using the action + +To use PSDocs: + +1. See [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file). +2. Reference `Microsoft/ps-docs@main`. +For example: + +```yaml +name: CI +on: [push] +jobs: + docs: + runs-on: ubuntu-latest + steps: + + - name: Checkout + uses: actions/checkout@main + + - name: Generate docs + uses: Microsoft/ps-docs@main +``` + +3. Run the workflow. ## Contributing -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. +This project welcomes contributions and suggestions. Most contributions require you to +agree to a Contributor License Agreement (CLA) declaring that you have the right to, +and actually do, grant us the rights to use your contribution. For details, visit +https://cla.microsoft.com. -When you submit a pull request, a CLA bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. +When you submit a pull request, a CLA-bot will automatically determine whether you need +to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the +instructions provided by the bot. You will only need to do this once across all repositories using our CLA. + +## Code of Conduct This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -## Trademarks +## Maintainers -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft -trademarks or logos is subject to and must follow -[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). -Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. +- [Bernie White](https://github.com/BernieWhite) + +## License + +This project is [licensed under the MIT License](LICENSE). + +[change log]: CHANGELOG.md diff --git a/SECURITY.md b/SECURITY.md index f7b8998..bb5af99 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,10 +1,12 @@ - +# Security policy + + ## Security 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/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +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. ## Reporting Security Issues @@ -12,9 +14,9 @@ If you believe you have found a security vulnerability in any Microsoft-owned re Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). -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 [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). +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). -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). +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). 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: @@ -38,4 +40,4 @@ We prefer all communications to be in English. Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). - \ No newline at end of file + diff --git a/SUPPORT.md b/SUPPORT.md index dc72f0e..f11c865 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,25 +1,16 @@ -# TODO: The maintainer of this repo has not yet edited this file - -**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project? - -- **No CSS support:** Fill out this template with information about how to file issues and get help. -- **Yes CSS support:** Fill out an intake form at [aka.ms/spot](https://aka.ms/spot). CSS will work with/help you to determine next steps. More details also available at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). -- **Not sure?** Fill out a SPOT intake as though the answer were "Yes". CSS will help you decide. - -*Then remove this first heading from this SUPPORT.MD file before publishing your repo.* - # Support -## How to file issues and get help +## How to file issues and get help -This project uses GitHub Issues to track bugs and feature requests. Please search the existing -issues before filing new issues to avoid duplicates. For new issues, file your bug or -feature request as a new Issue. +This project uses GitHub Issues to track bugs and feature requests. +Please search the existing issues before filing new issues to avoid duplicates. -For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE -FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER -CHANNEL. WHERE WILL YOU HELP PEOPLE?**. +- For new issues, file your bug or feature request as a new [issue]. +- For help, discussion, and support questions about using this project, join or start a [discussion]. -## Microsoft Support Policy +## Microsoft Support Policy -Support for this **PROJECT or PRODUCT** is limited to the resources listed above. +Support for this project/ product is limited to the resources listed above. + +[issue]: https://github.com/microsoft/ps-docs/issues +[discussion]: https://github.com/microsoft/ps-docs/discussions diff --git a/action.yml b/action.yml new file mode 100644 index 0000000..303e39d --- /dev/null +++ b/action.yml @@ -0,0 +1,41 @@ +name: 'PSDocs' +description: 'Generate documentation from Infrastructure as Code (IaC) using GitHub Actions.' +author: 'Microsoft' +branding: + icon: 'book-open' + color: 'blue' +inputs: + + inputPath: + description: 'The path PSDocs will look for files to input files.' + default: '' + required: false + + modules: + description: 'A comma separated list of modules to use containing document definitions.' + default: '' + required: false + + source: + description: 'An path containing definitions to use for generating documentation.' + default: '.ps-docs/' + required: false + + outputPath: + description: 'The path to write documentation to.' + default: '' + required: false + + path: + description: 'The working directory PSDocs is run from.' + default: '' + required: false + + prerelease: + description: 'Determine if a pre-release module version is installed.' + default: 'false' + required: false + +runs: + using: 'docker' + image: 'Dockerfile' diff --git a/docs/CHANGELOG-v0.md b/docs/CHANGELOG-v0.md new file mode 100644 index 0000000..c4f3d46 --- /dev/null +++ b/docs/CHANGELOG-v0.md @@ -0,0 +1,3 @@ +# Change log + +- No releases yet. diff --git a/powershell.ps1 b/powershell.ps1 new file mode 100644 index 0000000..c5ee286 --- /dev/null +++ b/powershell.ps1 @@ -0,0 +1,173 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +# +# PSDocs +# + +# See details at: https://github.com/Microsoft/ps-docs + +[CmdletBinding()] +param ( + # The working directory PSDocs is run from. + [Parameter(Mandatory = $False)] + [String]$Path = $Env:INPUT_PATH, + + # The path PSDocs will look for files to input files. + [Parameter(Mandatory = $False)] + [String]$InputPath = $Env:INPUT_INPUTPATH, + + # An path containing definitions to use for generating documentation. + [Parameter(Mandatory = $False)] + [String]$Source = $Env:INPUT_SOURCE, + + # A comma separated list of modules to use containing document definitions. + [Parameter(Mandatory = $False)] + [String]$Modules = $Env:INPUT_MODULES, + + # The path to write documentation to. + [Parameter(Mandatory = $False)] + [String]$OutputPath = $Env:INPUT_OUTPUTPATH, + + # Determine if a pre-release module version is installed. + [Parameter(Mandatory = $False)] + [String]$PreRelease = $Env:INPUT_PRERELEASE +) + +$workspacePath = $Env:GITHUB_WORKSPACE; +$ProgressPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue; +if ($Env:SYSTEM_DEBUG -eq 'true') { + $VerbosePreference = [System.Management.Automation.ActionPreference]::Continue; +} + +# Set workspace +if ([String]::IsNullOrEmpty($workspacePath)) { + $workspacePath = $PWD; +} + +# Set Path +if ([String]::IsNullOrEmpty($Path)) { + $Path = $workspacePath; +} +else { + $Path = Join-Path -Path $workspacePath -ChildPath $Path; +} + +# Set InputPath +if ([String]::IsNullOrEmpty($InputPath)) { + $InputPath = $Path; +} +else { + $InputPath = Join-Path -Path $Path -ChildPath $InputPath; +} + +# Set Source +if ([String]::IsNullOrEmpty($Source)) { + $Source = Join-Path -Path $Path -ChildPath '.ps-docs/'; +} +else { + $Source = Join-Path -Path $Path -ChildPath $Source; +} + +function WriteDebug { + [CmdletBinding()] + param ( + [Parameter(Position = 0, Mandatory = $True)] + [String]$Message + ) + process { + if ($Env:SYSTEM_DEBUG -eq 'true' -or $Env:ACTIONS_STEP_DEBUG -eq 'true') { + Write-Host "::debug::$Message"; + } + } +} + +# Setup paths for importing modules +$modulesPath = '/ps_modules/'; +if ((Get-Variable -Name IsMacOS -ErrorAction Ignore) -or (Get-Variable -Name IsLinux -ErrorAction Ignore)) { + $moduleSearchPaths = $Env:PSModulePath.Split(':', [System.StringSplitOptions]::RemoveEmptyEntries); + if ($modulesPath -notin $moduleSearchPaths) { + $Env:PSModulePath += [String]::Concat($Env:PSModulePath, ':', $modulesPath); + } +} +else { + $moduleSearchPaths = $Env:PSModulePath.Split(';', [System.StringSplitOptions]::RemoveEmptyEntries); + if ($modulesPath -notin $moduleSearchPaths) { + $Env:PSModulePath += [String]::Concat($Env:PSModulePath, ';', $modulesPath); + } +} + +$moduleNames = @() +if (![String]::IsNullOrEmpty($Modules)) { + $moduleNames = $Modules.Split(',', [System.StringSplitOptions]::RemoveEmptyEntries); +} +$moduleParams = @{ + Scope = 'CurrentUser' + Force = $True +} +if ($PreRelease -eq 'true') { + $moduleParams['AllowPrerelease'] = $True; +} + +# Install each module if not already installed +foreach ($m in $moduleNames) { + $m = $m.Trim(); + Write-Host "> Checking module: $m"; + if ($Null -eq (Get-InstalledModule -Name $m -ErrorAction Ignore)) { + Write-Host ' - Installing module'; + $Null = Install-Module -Name $m @moduleParams -AllowClobber; + } + else { + Write-Host ' - Already installed'; + } + # Check + if ($Null -eq (Get-InstalledModule -Name $m)) { + Write-Host " - Failed to install"; + } + else { + Write-Host " - Using version: $((Get-InstalledModule -Name $m).Version)"; + } +} + +Write-Host ''; +Write-Host "[info] Using Action: $Env:GITHUB_ACTION"; +Write-Host "[info] Using PWD: $PWD"; +Write-Host "[info] Using Path: $Path"; +Write-Host "[info] Using Source: $Source"; +Write-Host "[info] Using Baseline: $Baseline"; +Write-Host "[info] Using InputType: $InputType"; +Write-Host "[info] Using InputPath: $InputPath"; +Write-Host "[info] Using OutputFormat: $OutputFormat"; +Write-Host "[info] Using OutputPath: $OutputPath"; + +try { + Push-Location -Path $Path; + $invokeParams = @{ + Path = $Source + ErrorAction = 'Stop' + } + WriteDebug "Preparing command-line:"; + WriteDebug ([String]::Concat('-Path ''', $Source, '''')); + if (![String]::IsNullOrEmpty($Modules)) { + $moduleNames = $Modules.Split(',', [System.StringSplitOptions]::RemoveEmptyEntries); + $invokeParams['Module'] = $moduleNames; + WriteDebug ([String]::Concat('-Module ', [String]::Join(', ', $moduleNames))); + } + if (![String]::IsNullOrEmpty($OutputPath)) { + $invokeParams['OutputPath'] = $OutputPath; + WriteDebug ([String]::Concat('-OutputPath ''', $OutputPath, '''')); + } + + WriteDebug 'Running ''Invoke-PSDocument''.'; + Write-Host ''; + Write-Host '---'; + Invoke-PSDocument @invokeParams -InputPath $InputPath; +} +catch { + Write-Host "::error::An error occured generating documentation."; + $Host.SetShouldExit(1); +} +finally { + Pop-Location; +} +Write-Host '---'; diff --git a/ps-project.yaml b/ps-project.yaml new file mode 100644 index 0000000..e488169 --- /dev/null +++ b/ps-project.yaml @@ -0,0 +1,24 @@ + +info: + name: PSDocs + description: Generate documentation from Infrastructure as Code (IaC) using GitHub Actions. + url: https://github.com/Microsoft/ps-docs + +repository: + type: git + url: https://github.com/Microsoft/ps-docs.git + +license: MIT + +bugs: + url: https://github.com/Microsoft/ps-docs/issues + +# modules: +# PSDocs: '@pre >=0.9.0' + +tasks: + clear: + steps: + - gitPrune: + name: origin + removeGone: true diff --git a/ps-rule.yaml b/ps-rule.yaml new file mode 100644 index 0000000..6650407 --- /dev/null +++ b/ps-rule.yaml @@ -0,0 +1,18 @@ +# +# PSRule configuration +# + +# Please see the documentation for all configuration options: +# https://microsoft.github.io/PSRule/ + +requires: + PSRule: '@pre >=1.4.0' + +output: + culture: + - en-US + +input: + pathIgnore: + - '*.md' + - '.vscode/'