Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edits based on new linting rules #79

Merged
merged 2 commits into from
Jul 11, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

<!-- link references -->
[blog]: https://devblogs.microsoft.com/powershell-community/tag/crescendo/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand Down
12 changes: 6 additions & 6 deletions reference/ps-modules/PlatyPS/New-ExternalHelp.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ New-ExternalHelp -Path <String[]> -OutputPath <String> [-ApplicableTag <String[]
## DESCRIPTION

The `New-ExternalHelp` cmdlet creates an external help file based on markdown help files supported
by PlatyPS. You can ship this with a module to provide help by using the `Get-Help` cmdlet.
by PlatyPS. You can ship this with a module to provide help using the `Get-Help` cmdlet.

If the markdown files that you specify do not follow the PlatyPS
If the markdown files that you specify don't follow the PlatyPS
[Schema](https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md), this cmdlet returns
error messages.

Expand Down Expand Up @@ -60,8 +60,8 @@ Mode LastWriteTime Length Name
```

This command creates an external help file in the specified location. This command specifies the
*Force* parameter, therefore, it overwrites an existing file. The command specifies Unicode encoding
for the created file.
**Force** parameter, therefore, it overwrites an existing file. The command specifies Unicode
encoding for the created file.

### Example 3: Write warnings and errors to file

Expand Down Expand Up @@ -176,7 +176,7 @@ Specifies the maximum line length when generating "about" help text files. Other
not affected by this parameter. For more information, see
[New-MarkdownAboutHelp](New-MarkdownAboutHelp.md).

Lines inside code blocks are not wrapped and are not affected by the **MaxAboutWidth** parameter.
Lines inside code blocks aren't wrapped and aren't affected by the **MaxAboutWidth** parameter.

```yaml
Type: Int32
Expand All @@ -198,7 +198,7 @@ The path must include the location and name of the folder and file name with the
JSON object contains three properties: **Message**, **FilePath**, and **Severity** (Warning or
Error).

If this path is not provided, no log will be generated.
If this path isn't provided, no log is generated.

```yaml
Type: String
Expand Down
11 changes: 6 additions & 5 deletions reference/ps-modules/PlatyPS/New-ExternalHelpCab.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ We recommend that you provide as content only about_ topics and the output from

This cmdlet uses metadata stored in the module markdown file to name your .cab file. This naming
matches the pattern that the Windows PowerShell help system requires for use as updatable help. This
metadata is part of the module file created by using the [New-MarkdownHelp](New-MarkdownHelp.md)
metadata is part of the module file created using the [New-MarkdownHelp](New-MarkdownHelp.md)
cmdlet with the **WithModulePage** parameter.

This cmdlet also generates or updates an existing `helpinfo.xml` file. That file provides versioning
Expand Down Expand Up @@ -65,8 +65,9 @@ Accept wildcard characters: False

### -LandingPagePath

Specifies the full path of the Module Markdown file that contains all the metadata required to name the .cab file.
For the required metadata, run `New-MarkdownHelp` with the *WithLandingPage* parameter.
Specifies the full path of the Module Markdown file that contains all the metadata required to name
the .cab file. For the required metadata, run `New-MarkdownHelp` with the **WithLandingPage**
parameter.

```yaml
Type: String
Expand Down Expand Up @@ -123,13 +124,13 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable

### None

You cannot pipe values to this cmdlet.
You can't pipe values to this cmdlet.

## OUTPUTS

### None

This cmdlet does not generate output. The cmdlet saves its results in the output folder that the
This cmdlet doesn't generate output. The cmdlet saves its results in the output folder that the
**OutputPath** parameter specifies.

## NOTES
Expand Down
19 changes: 10 additions & 9 deletions reference/ps-modules/PlatyPS/New-MarkdownHelp.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Mode LastWriteTime Length Name
-a---- 5/22/2016 6:53 PM 664 Command03.md
```

The first command creates a function named Command03 by using standard Windows PowerShell syntax.
The first command creates a function named `Command03` using standard Windows PowerShell syntax.

The second command creates help for that stub function in the .\docs folder.

Expand All @@ -86,7 +86,8 @@ Mode LastWriteTime Length Name
-a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md
```

The first command loads the PlatyPS module into the current session by using the `Import-Module` cmdlet.
The first command loads the **PlatyPS** module into the current session using the `Import-Module`
cmdlet.

The second command creates help for all the cmdlets in the PlatyPS module. It stores them in the
`.\docs` folder. This command specifies the **Force** parameter. Therefore, it overwrites existing
Expand All @@ -109,7 +110,7 @@ Mode LastWriteTime Length Name
-a---- 5/22/2016 6:56 PM 15320 Set-PSReadLineOption.md
```

This command creates help in markdown format for the specified help MAML file. You do not have to
This command creates help in markdown format for the specified help MAML file. You don't have to
load the module, as in the previous example. If the module is already loaded, this command creates
help based on the MAML file, not on the currently installed module.

Expand Down Expand Up @@ -263,7 +264,7 @@ Specifies metadata that this cmdlet includes in the help markdown files as a has
string-to-sting key-value pairs. This cmdlet writes the metadata in the header of each markdown help
file.

The `New-ExternalHelp` cmdlet does not use this metadata. External tools can use this metadata.
The `New-ExternalHelp` cmdlet doesn't use this metadata. External tools can use this metadata.

```yaml
Type: Hashtable
Expand Down Expand Up @@ -329,7 +330,7 @@ Accept wildcard characters: False

### -NoMetadata

Indicates that this cmdlet does not write any metadata in the generated markdown.
Indicates that this cmdlet doesn't write any metadata in the generated markdown.

```yaml
Type: SwitchParameter
Expand All @@ -345,8 +346,8 @@ Accept wildcard characters: False

### -OnlineVersionUrl

Specifies the URL where the updatable help function downloads updated help. If you do not specify a
value, the cmdlet uses an empty string.
Specifies the address where the updatable help function downloads updated help. If you don't specify
a value, the cmdlet uses an empty string.

```yaml
Type: String
Expand Down Expand Up @@ -379,8 +380,8 @@ Accept wildcard characters: False
### -WithModulePage

Indicates that this cmdlet creates a module page in the output folder. This file has the name that
the **ModuleName** parameter specifies. If you did not specify that parameter, the cmdlet supplies
the default name MamlModule. You can overwrite this setting by using **ModulePagePath** which allows
the **ModuleName** parameter specifies. If you didn't specify that parameter, the cmdlet supplies
the default name `MamlModule`. You can overwrite this setting using **ModulePagePath** which allows
you to define different path for module page

```yaml
Expand Down