Skip to content

Commit

Permalink
Update documentation (microsoft#2644)
Browse files Browse the repository at this point in the history
  • Loading branch information
BernieWhite authored Nov 30, 2024
1 parent 935ae55 commit 66f6388
Show file tree
Hide file tree
Showing 8 changed files with 70 additions and 36 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ site/
server/
node_modules/
.vscode-test/
.cache/
*.vsix
*.user
src/**/*-help.xml
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
PSRule provides a command-line interface (CLI) to run rules and analyze results.
This article describes the commands available in the CLI.

For details on installing the PSRule CLI, see [Install PSRule](../../install.md#with-cli).
For details on installing the PSRule CLI, see [Install PSRule](../../setup/index.md#with-cli).

## Commands

Expand Down
4 changes: 2 additions & 2 deletions docs/quickstart/standalone-rule.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@ Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser
!!! Tip
To make you editing experience even better, consider installing the Visual Studio Code extension.

[2]: ../install-instructions.md#installing-powershell
[3]: ../install-instructions.md#getting-the-modules
[2]: ../setup/index.md#with-powershell
[3]: ../setup/index.md#getting-the-modules

## Scenario - Test for image files

Expand Down
17 changes: 2 additions & 15 deletions docs/install.md → docs/setup/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ reviewed: 2024-02-16
author: BernieWhite
---

# Install PSRule
# Setting up PSRule

PSRule supports running within continuous integration (CI) systems or locally.
It is shipped as a PowerShell module which makes it easy to install and distribute updates.
Expand All @@ -22,7 +22,7 @@ Create custom tests for your organization | With [Visual Studio Code][11] _and_
[8]: #with-github-actions
[9]: #with-azure-pipelines
[10]: #with-powershell
[11]: #with-visual-studio-code
[11]: vscode.md
[13]: #with-cli

## With GitHub Actions
Expand Down Expand Up @@ -101,19 +101,6 @@ This will automatically install compatible versions of all dependencies.

[2]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule

## With Visual Studio Code

[:octicons-download-24: Extension][12]

An extension for Visual Studio Code is available for an integrated experience using PSRule.
The Visual Studio Code extension includes a built-in tasks and configuration schemas for working with PSRule.

<p align="center">
<img src="https://raw.githubusercontent.com/microsoft/PSRule-vscode/main/docs/images/tasks-provider.png" alt="Built-in tasks shown in task list" />
</p>

[12]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode

## With CLI

PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available.
Expand Down
32 changes: 32 additions & 0 deletions docs/setup/vscode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# PSRule in Visual Studio Code

An extension for Visual Studio Code is available for an integrated experience using PSRule.
The Visual Studio Code extension includes a built-in tasks and configuration schemas for working with PSRule.

<p align="center">
<img src="https://raw.githubusercontent.com/microsoft/PSRule/main/docs/images/tasks-provider.png" alt="Built-in tasks shown in task list" />
</p>

## Installation

1. Download and install Visual Studio Code.
2. Install the [PSRule extension from the marketplace][1].

Alternatively you can separately download the extension as a packaged `.vsix` file and install it locally.

[1]: https://marketplace.visualstudio.com/items?itemName=ps-rule.vscode-ps-rule

## Updates

Extension updates for PSRule are released on a regular basis.
Each extension update includes all the key components to make PSRule work without additional installations.

By default, Visual Studio Code automatically updates extensions installed from the marketplace when updates are available.

!!! Note
You can disable automatic updates of Visual Studio Code extensions if you prefer to update PSRule on your own schedule.
It is also possible to switch to an older version of PSRule from v3.

For details see [Manage extensions][2].

[2]: https://code.visualstudio.com/docs/editor/extension-marketplace#_manage-extensions
4 changes: 4 additions & 0 deletions docs/updates/v3_0.md → docs/updates/v3.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ date: 2024-11-30
version: 3.0
---

# nnn nnn (v3.0)

For a detailed change log see [v3](../CHANGELOG-v3.md).

## Visual Studio Code

### New home and identity
Expand Down
2 changes: 1 addition & 1 deletion docs/validating-locally.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This allows you to test Infrastructure as Code (IaC) artifacts before pushing ch
!!! Tip
If you haven't already, follow the instructions on [installing locally][1] before continuing.

[1]: install.md#with-powershell
[1]: setup/index.md#with-powershell

## With Visual Studio Code

Expand Down
44 changes: 27 additions & 17 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,20 +44,21 @@ nav:
- Overview:
- About: about.md
- Features: features.md
- FAQ: faq.md
- Install: install.md
- Setup:
- Index: setup/index.md
- Visual Studio Code: setup/vscode.md
- Quickstarts:
- Create a standalone rule: quickstart/standalone-rule.md
- Authoring rules:
- User guide:
- Creating your pipeline: creating-your-pipeline.md
- Validating locally: validating-locally.md
- Analysis output: analysis-output.md
- Developer guide:
- Testing infrastructure: authoring/testing-infrastructure.md
- Using expressions: authoring/using-expressions.md
- Storing and naming rules: authoring/storing-rules.md
- Packaging rules in a module: authoring/packaging-rules.md
- Writing rule help: authoring/writing-rule-help.md
- Running rules:
- Creating your pipeline: creating-your-pipeline.md
- Validating locally: validating-locally.md
- Analysis output: analysis-output.md
- Tutorials:
- Validate Azure resource configuration: scenarios/azure-resources/azure-resources.md
- Azure resource tagging example: scenarios/azure-tags/azure-tags.md
Expand All @@ -75,20 +76,21 @@ nav:
- Troubleshooting: troubleshooting.md
- License and contributing: license-contributing.md
- Related projects: related-projects.md
- Releases:
- Change log:
- v3: 'CHANGELOG-v3.md'
- v2: https://microsoft.github.io/PSRule/stable/CHANGELOG-v2/
- v1: https://microsoft.github.io/PSRule/stable/CHANGELOG-v1/
- v0: https://microsoft.github.io/PSRule/stable/CHANGELOG-v0/
- Upgrade notes: upgrade-notes.md
- Deprecations: deprecations.md
- Changes and versioning: versioning.md
- Support: support.md
# - Setup:
# - Configuring options: setup/configuring-options.md
# - Configuring rule defaults: setup/configuring-rules.md
# - Configuring expansion: setup/configuring-expansion.md
- Updates:
# - December 2024: updates/v3.0.md
- Change log:
- v3: 'CHANGELOG-v3.md'
- v2: https://microsoft.github.io/PSRule/stable/CHANGELOG-v2/
- v1: https://microsoft.github.io/PSRule/stable/CHANGELOG-v1/
- v0: https://microsoft.github.io/PSRule/stable/CHANGELOG-v0/
- Upgrade notes: upgrade-notes.md
- Deprecations: deprecations.md
- Changes and versioning: versioning.md
- Reference:
- PowerShell cmdlets:
- Assert-PSRule: commands/PSRule/en-US/Assert-PSRule.md
Expand Down Expand Up @@ -119,6 +121,7 @@ nav:
- Selectors: concepts/PSRule/en-US/about_PSRule_Selectors.md
- Suppression Groups: concepts/PSRule/en-US/about_PSRule_SuppressionGroups.md
- Variables: concepts/PSRule/en-US/about_PSRule_Variables.md
- FAQ: faq.md
- Addons:
- Additional modules: addon-modules.md

Expand Down Expand Up @@ -153,16 +156,23 @@ plugins:
enable_creation_date: true
fallback_to_build_date: true
- git-committers:
enabled: !ENV [GITHUB_ACTIONS, false]
repository: microsoft/PSRule
branch: main
- mkdocs-simple-hooks:
hooks:
on_page_markdown: 'docs.hooks:replace_maml'
- search
- tags:
tags: false
- redirects:
redirect_maps:
'authoring/writing-rules.md': 'authoring/testing-infrastructure.md'
'install-instructions.md': 'install.md'
'install-instructions.md': 'setup/index.md'
'install.md': 'setup/index.md'

exclude_docs: |
specs/
extra:
version:
Expand Down

0 comments on commit 66f6388

Please sign in to comment.