From c8e709e992a23d172a4627483d2deb84b8e6f4f6 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 11 Jul 2022 09:20:07 -0500 Subject: [PATCH 1/5] Edits based on new linting rules (#79) * Edits based on new linting rules * Apply suggestions from code review Co-authored-by: Mikey Lombardi (He/Him) Co-authored-by: Mikey Lombardi (He/Him) --- .../advanced/using-crescendo-cmdlets.md | 23 +++++++++---------- .../Get-ScriptAnalyzerRule.md | 4 ++-- .../ps-modules/PlatyPS/New-ExternalHelp.md | 12 +++++----- .../ps-modules/PlatyPS/New-ExternalHelpCab.md | 11 +++++---- .../ps-modules/PlatyPS/New-MarkdownHelp.md | 19 +++++++-------- 5 files changed, 35 insertions(+), 34 deletions(-) diff --git a/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md b/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md index 4e482b0..149e197 100644 --- a/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md +++ b/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md @@ -8,9 +8,9 @@ title: Create a Crescendo configuration using the Crescendo cmdlets The Crescendo module includes a set of cmdlets that create various Crescendo object types. You can use these cmdlets to create a Crescendo configuration without the need to manually edit a JSON file. -During the design of Crescendo, these cmdlets were created before the decision that module and -cmdlet creation could be better served by a declarative approach. Their utility was still obvious, -so the decision was made to support both approaches. +During the design of Crescendo, we created these cmdlets before the decision that module and cmdlet +creation could be better served by a declarative approach. Their utility was still appreciated, so +we decided to support both approaches. > [!IMPORTANT] > Since developer tools like Visual Studio Code (VS Code) provide IntelliSense based on the JSON @@ -204,15 +204,14 @@ Export-CrescendoModule -ConfigurationFile vssadmin.json -ModuleName .\vssadmin.p ## Advanced use cases The Crescendo cmdlets are powerful tools that can be used in advanced scenarios to create -configurations and build modules. There are several advanced examples that come bundled with the -Crescendo module. These can be found in the `Experimental\HelpParsers` folder of the -**Microsoft.PowerShell.Crescendo** module. These experimental examples show how you can parse the -help output of a command-line tool and use that information to create a Crescendo configuration for -a module that wrap the tool. The [README.md][README.md] file provides a detailed explanation of the -design of these help parsers. - -Examples like these help parsers could be used in a CI/CD pipeline to build new versions of a module -when the command-line tool changes. +configurations and build modules. There are several advanced examples in the `Experimental\HelpParsers` +folder of the **Microsoft.PowerShell.Crescendo** module. These experimental examples show how you +can parse the help output of a command-line tool and use that information to create a Crescendo +configuration for a module that wraps the tool. The [README.md][README.md] file provides a detailed +explanation of the design of these help parsers. + +You could use these help parsers in a CI/CD pipeline to build new versions of a module when the +command-line tool changes. [blog]: https://devblogs.microsoft.com/powershell-community/tag/crescendo/ diff --git a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md index ccb56c6..5aa735e 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md +++ b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md @@ -92,7 +92,7 @@ Enter the path to a .NET assembly or module that contains Script Analyzer rules. one value, but wildcards are supported. To get rules in subdirectories of the path, use the **RecurseCustomRulePath** parameter. -You can create custom rules by using a custom .NET assembly or a PowerShell module, such as the +You can create custom rules using a .NET assembly or a PowerShell module, such as the [Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1) in the GitHub repository. @@ -173,7 +173,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### None -You cannot pipe input to this cmdlet. +You can't pipe input to this cmdlet. ## OUTPUTS diff --git a/reference/ps-modules/PlatyPS/New-ExternalHelp.md b/reference/ps-modules/PlatyPS/New-ExternalHelp.md index b0f03b9..fabdbf9 100644 --- a/reference/ps-modules/PlatyPS/New-ExternalHelp.md +++ b/reference/ps-modules/PlatyPS/New-ExternalHelp.md @@ -21,9 +21,9 @@ New-ExternalHelp -Path -OutputPath [-ApplicableTag Date: Tue, 12 Jul 2022 12:01:18 -0500 Subject: [PATCH 2/5] (AB#4072) Add stale content reporting (#80) This change adds monthly reporting to the repository to inspect the conceptual documentation for stale content (defined as anything with an `ms.date` value more than 330 days older than the current date), writing the report in the console logs, to the GitHub Action summary, and uploading the data in CSV format as a GitHub Action artifact. --- .github/workflows/stale-content.yml | 30 +++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 .github/workflows/stale-content.yml diff --git a/.github/workflows/stale-content.yml b/.github/workflows/stale-content.yml new file mode 100644 index 0000000..27b7d02 --- /dev/null +++ b/.github/workflows/stale-content.yml @@ -0,0 +1,30 @@ +# This workflow inspects the specified relative folder path for stale documents, +# defined as any markdown files with an `ms.date` key whose value is more than +# 330 days from the time this workflow is run. +# +# It ignores the folders in the exclude_path_segment input as those documents +# are not expected to be fresh at this time. +name: Reporting +on: + schedule: + # midnight UTC on the first of every month + - cron: 0 0 1 * * +permissions: + contents: read +jobs: + Report: + name: Stale Content + runs-on: windows-latest + defaults: + run: + shell: pwsh + steps: + - name: Checkout Repository + id: checkout_repo + uses: actions/checkout@v3 + - name: Write Report + uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/stale-content/v1@main + with: + relative_folder_path: | + reference/docs-conceptual + upload_artifact: true From 9e9bbbb80523879d511e223bb7288180ea525235 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Fri, 15 Jul 2022 12:49:10 -0500 Subject: [PATCH 3/5] (MAINT) Limit cron workflows to upstream (#81) --- .github/workflows/expectations.yml | 1 + .github/workflows/stale-content.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/workflows/expectations.yml b/.github/workflows/expectations.yml index e69200a..750e067 100644 --- a/.github/workflows/expectations.yml +++ b/.github/workflows/expectations.yml @@ -12,6 +12,7 @@ permissions: jobs: Expectations: name: Share Expectations on Community PRs + if: github.repository_owner == 'MicrosoftDocs' runs-on: windows-latest defaults: run: diff --git a/.github/workflows/stale-content.yml b/.github/workflows/stale-content.yml index 27b7d02..87db154 100644 --- a/.github/workflows/stale-content.yml +++ b/.github/workflows/stale-content.yml @@ -14,6 +14,7 @@ permissions: jobs: Report: name: Stale Content + if: github.repository_owner == 'MicrosoftDocs' runs-on: windows-latest defaults: run: From ab42513fd7ba220ec039e0df4e8e9d1a95f94946 Mon Sep 17 00:00:00 2001 From: Tami Fosmark Date: Wed, 20 Jul 2022 13:55:16 -0700 Subject: [PATCH 4/5] Update toc.yml (#82) --- reference/breadcrumb/toc.yml | 38 +++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/reference/breadcrumb/toc.yml b/reference/breadcrumb/toc.yml index 84f1103..1cce9f4 100644 --- a/reference/breadcrumb/toc.yml +++ b/reference/breadcrumb/toc.yml @@ -1,15 +1,25 @@ -items: - - name: Docs - tocHref: / - topicHref: / +- name: Docs + tocHref: / + topicHref: / + items: + - name: PowerShell + tocHref: /powershell/ + topicHref: /powershell items: - - name: PowerShell - tocHref: /powershell/ - topicHref: /powershell - items: - - name: Utility Modules - tocHref: /powershell/utility-modules/ - topicHref: /powershell/utility-modules/overview - - name: Utility Modules - tocHref: /powershell/module/ - topicHref: /powershell/utility-modules/overview + - name: Utility Modules + tocHref: /powershell/utility-modules/ + topicHref: /powershell/utility-modules/overview + items: + - name: Crescendo + tocHref: /powershell/module/crescendo/ + topicHref: /powershell/utility-modules/crescendo/overview + - name: PlatyPS + tocHref: /powershell/module/platyps/ + topicHref: /powershell/utility-modules/platyps/overview + - name: PSScriptAnalyzer + tocHref: /powershell/module/psscriptanalyzer/ + topicHref: /powershell/utility-modules/psscriptanalyzer/overview + - name: SecretManagement and SecretStore + tocHref: /powershell/module/secretmanagement/ + topicHref: /powershell/utility-modules/secretmanagement/overview + From e6d5bb245df258e1254ee2dc12e07dd4afe1de63 Mon Sep 17 00:00:00 2001 From: Tami Fosmark Date: Wed, 20 Jul 2022 14:05:15 -0700 Subject: [PATCH 5/5] [BrokenLinks] fix breacrumb config (part 2) (#84) * Update toc.yml * Update docfx.json --- reference/docfx.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/docfx.json b/reference/docfx.json index ef0275c..a9a8484 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -78,7 +78,7 @@ "globalMetadata": { "ROBOTS": "INDEX, FOLLOW", "apiPlatform": "powershell", - "breadcrumb_path": "/powershell/PowerShell-Docs-Modules/breadcrumb/toc.json", + "breadcrumb_path": "/powershell/utility-modules/breadcrumb/toc.json", "feedback_github_repo": "MicrosoftDocs/PowerShell-Docs-Modules", "feedback_system": "GitHub", "ms.devlang": "powershell", @@ -107,4 +107,4 @@ } } } -} \ No newline at end of file +}