Skip to content

Commit 4176fb8

Browse files
sdwheelersdwheeler
authored
Merge pull request #699 from sdwheeler/sdw-docs-reorg
Reorganizing documentation in preparation for p1 release
2 parents f9fa128 + bfbb78e commit 4176fb8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+4529
-100
lines changed

‎CHANGELOG.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
1-
CHANGELOG
2-
-------------
1+
# CHANGELOG
32

43
## Not released
54

6-
# 0.14.2
5+
## 1.0.0-preview1
6+
7+
- Total rewrite of the module in C#
8+
9+
## 0.14.2
710

811
- Add HelpInfoUri for platyPS module
912
- CI changes to exclude build on v2 branch
@@ -13,21 +16,21 @@ CHANGELOG
1316
- Make sure for script module .psm1 is added to the external help file metadata for nested module
1417
- New-Yaml help generates YAML for common parameters
1518

16-
# 0.14.1
19+
## 0.14.1
1720

1821
- Fix appveyor build script
1922
- Update-Help for selected modules only
2023
- Pin Pester to version 4.10.1
2124
- Add makecab directive to set size limit to `CDROM`
2225

23-
# 0.14.0
26+
## 0.14.0
2427

2528
* Fix passing `ExcludeDontShow` flag to modules (#459)
2629
* Make `CommonParameters` text use proper link format (#449)
2730
* Modified `GetSchemaVersion` function to assume `2.0.0` if no schema version found (#452)
2831
* Fix errors for `New-MarkdownHelp` `ps1` input (#450)
2932

30-
# 0.13.0
33+
## 0.13.0
3134

3235
* Fix `Update-MarkdownHelp` to not rewrite files if there are not updates (#412) (Thanks @iricigor)
3336
* Add `-ModulePagePath` parameter to `New-MarkdownHelp` for better placement of generated file (#416) (Thanks @PrzemyslawKlys)

‎README.md

Lines changed: 71 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,131 @@
1-
[![Build status](https://ci.appveyor.com/api/projects/status/u65tnar0cfkmqywl/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/markdown-maml/branch/master)
2-
[![Build status](https://travis-ci.org/PowerShell/platyPS.svg?branch=master)](https://travis-ci.org/PowerShell/platyPS/builds)
3-
4-
[![Join the chat at https://gitter.im/PowerShell/platyPS](https://badges.gitter.im/PowerShell/platyPS.svg)](https://gitter.im/PowerShell/platyPS?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
5-
61
# PlatyPS
72

83
PlatyPS provides a way to:
94

10-
* Write PowerShell External Help in Markdown
11-
* Generate markdown help ([example](docs/Update-MarkdownHelp.md)) for your existing modules
12-
* Keep markdown help up-to-date with your code
5+
- Write PowerShell External Help in Markdown
6+
- Generate markdown help
7+
- Keep markdown help up-to-date with your code
8+
- Create updateable help files
139

14-
Markdown help docs can be generated from old external help files (also known as MAML-xml help), the command objects (reflection), or both.
15-
16-
PlatyPS can also generate cab files for [`Update-Help`](https://technet.microsoft.com/en-us/library/hh849720.aspx).
10+
Markdown help docs can be generated from old external help files (also known as MAML-xml help), the
11+
command objects (reflection), or both.
1712

1813
## Why?
1914

20-
Traditionally PowerShell external help files have been authored by hand or using complex tool chains and rendered as MAML XML for use as console help.
21-
MAML is cumbersome to edit by hand, and common tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a solution for allow documenting PowerShell help in any editor or tool that supports Markdown.
15+
Traditionally PowerShell external help files have been authored by hand or using complex tool chains
16+
and rendered as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common
17+
tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is
18+
provided as a solution for allow documenting PowerShell help in any editor or tool that supports
19+
Markdown.
2220

23-
An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios (e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the codebase. PlatyPS does not need source access to generate documentation.
21+
An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios
22+
(e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have
23+
documentation abstracted away from the codebase. PlatyPS doesn't need source access to generate
24+
documentation.
2425

25-
Markdown is designed to be human-readable, without rendering. This makes writing and editing easy and efficient.
26-
Many editors support it ([Visual Studio Code](https://code.visualstudio.com/), [Sublime Text](http://www.sublimetext.com/), etc), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.
26+
Markdown is designed to be human-readable, without rendering. This makes writing and editing easy
27+
and efficient. Many editors support it, including [Visual Studio Code][04], and many tools and
28+
collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.
2729

2830
## Common setups
2931

3032
There are 2 common setups that are used:
3133

3234
1. Use markdown as the source of truth and remove other types of help.
33-
2. Keep comment based help as the source of truth and periodically generate markdown for web-site publishing.
35+
1. Keep comment based help as the source of truth and periodically generate markdown for web-site
36+
publishing.
3437

35-
They both have advantages and use-cases, you should decide what's right for you.
36-
There is slight preference toward number 1 (markdown as the source).
38+
They both have advantages and use-cases, you should decide what's right for you. There is slight
39+
preference toward number 1 (markdown as the source).
3740

3841
## Quick start
3942

40-
* Install platyPS module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/platyPS):
43+
- Install platyPS module from the [PowerShell Gallery][07]:
4144

4245
```powershell
4346
Install-Module -Name platyPS -Scope CurrentUser
4447
Import-Module platyPS
4548
```
4649

47-
* Create initial Markdown help for `MyAwesomeModule` module:
50+
- Create initial Markdown help for `MyAwesomeModule` module:
4851

4952
```powershell
5053
# you should have module imported in the session
5154
Import-Module MyAwesomeModule
5255
New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs
5356
```
5457

55-
* Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content.
58+
- Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content.
59+
- Create external help from markdown help
5660

57-
* Create external help from markdown help
61+
```powershell
62+
New-ExternalHelp .\docs -OutputPath en-US\
63+
```
5864

59-
```powershell
60-
New-ExternalHelp .\docs -OutputPath en-US\
61-
```
62-
63-
* **Congratulations**, your help is now in markdown!
65+
**Congratulations**, your help is now in markdown!
6466

65-
* Now, if your module code changes, you can easily update your markdown help with
67+
- Now, if your module code changes, you can easily update your markdown help with
6668

67-
```powershell
68-
# re-import your module with latest changes
69-
Import-Module MyAwesomeModule -Force
70-
Update-MarkdownHelp .\docs
71-
```
69+
```powershell
70+
# re-import your module with latest changes
71+
Import-Module MyAwesomeModule -Force
72+
Update-MarkdownHelp .\docs
73+
```
7274

7375
### PlatyPS markdown schema
7476

75-
Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a **particular way**.
76-
We have defined a [**schema**](platyPS.schema.md) to determine how parameters are described, where scripts examples are shown, and so on.
77+
Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a
78+
**particular way**. We have defined a [**schema**][03] to determine how parameters are described,
79+
where scripts examples are shown, and so on.
7780

78-
The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell.
81+
The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell.
7982

80-
If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and `Update-MarkdownHelp`.
81-
You would not be able to generate extrenal help or update your markdown.
83+
If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and
84+
`Update-MarkdownHelp`. You would not be able to generate extrenal help or update your markdown.
8285

8386
It may be fine for some scenarios, i.e. you want to have online-only version of markdown.
8487

85-
## [Usage](docs)
88+
## [Usage][06]
8689

8790
Supported scenarios:
8891

89-
* Create Markdown
90-
* Using existing external help files (MAML schema, XML).
91-
* Using reflection
92-
* Using reflection and existing internal external help files.
93-
* For a single cmdlet
94-
* For an entire module
95-
96-
* Update existing Markdown through reflection.
97-
98-
* Create a module page <ModuleName>.md with summary. It will also allow you to create updatable help cab.
99-
100-
* Retrieve markdown metadata from markdown file.
101-
102-
* Create external help xml files (MAML) from platyPS Markdown.
103-
104-
* Create external help file cab
105-
106-
* Preview help from generated maml file.
92+
- Create Markdown
93+
- Using existing external help files (MAML schema, XML).
94+
- Using reflection
95+
- Using reflection and existing internal external help files.
96+
- For a single cmdlet
97+
- For an entire module
98+
- Update existing Markdown through reflection.
99+
- Create a module page `<ModuleName>.md` with summary. It will also allow you to create updatable
100+
help cab.
101+
- Retrieve markdown metadata from markdown file.
102+
- Create external help xml files (MAML) from platyPS Markdown.
103+
- Create external help file cab
104+
- Preview help from generated maml file.
107105

108106
## Remoting
109107

110-
PlatyPS supports working with [`Import-PSSession`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/import-pssession?view=powershell-6) aka implicit remoting.
111-
Just pass `-Session $Session` parameter to the platyPS cmdlets and it will do the rest.
108+
PlatyPS supports working with [Import-PSSession][05] aka implicit remoting. Just pass
109+
`-Session $Session` parameter to the platyPS cmdlets and it will do the rest.
112110

113111
## Build
114112

115-
For information about building from sources and contributing see [contributing guidelines](CONTRIBUTING.md).
113+
For information about building from sources and contributing see [contributing guidelines][02].
116114

117115
## Code of Conduct
118116

119-
Please see our [Code of Conduct](CODE_OF_CONDUCT.md) before participating in this project.
117+
Please see our [Code of Conduct][01] before participating in this project.
120118

121119
## Security Policy
122120

123-
For any security issues, please see our [Security Policy](SECURITY.md).
121+
For any security issues, please see our [Security Policy][08].
122+
123+
<!-- link references -->
124+
[01]: CODE_OF_CONDUCT.md
125+
[02]: docs/developer/platyPS/CONTRIBUTING.md
126+
[03]: docs/deveopler/platyPS.schema.md
127+
[04]: https://code.visualstudio.com/
128+
[05]: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/import-pssession
129+
[06]: https://learn.microsoft.com/powershell/module/platyps/
130+
[07]: https://www.powershellgallery.com/packages/platyPS
131+
[08]: SECURITY.md

‎docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
document type: cmdlet
3+
external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml
4+
HelpUri: ''
5+
Locale: en-US
6+
Module Name: Microsoft.PowerShell.PlatyPS
7+
ms.custom: OPS10
8+
ms.date: 09/17/2024
9+
PlatyPS schema version: 2024-05-01
10+
title: Compare-CommandHelp
11+
---
12+
13+
# Compare-CommandHelp
14+
15+
## SYNOPSIS
16+
17+
Compares two **CommandHelp** objects and produces a detailed report showing the differences.
18+
19+
## SYNTAX
20+
21+
### __AllParameterSets
22+
23+
```
24+
Compare-CommandHelp [-ReferenceCommandHelp] <CommandHelp> [-DifferenceCommandHelp] <CommandHelp>
25+
[-PropertyNamesToExclude <string[]>] [<CommonParameters>]
26+
```
27+
28+
## ALIASES
29+
30+
## DESCRIPTION
31+
32+
`Compare-CommandHelp` is a troubleshooting tool that compares two CommandHelp objects and produces a
33+
detailed report showing the differences. For example, you can use this to compare objects imported
34+
from different sources, such as two different versions of Markdown files.
35+
36+
## EXAMPLES
37+
38+
### Example 1
39+
40+
```powershell
41+
$refcmd = Import-MarkdownCommandHelp -Path .\v1\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md
42+
$diffcmd = Import-MarkdownCommandHelp -Path .\v2\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md
43+
Compare-CommandHelp -ReferenceCommandHelp $refcmd -DifferenceCommandHelp $diffcmd > .\diff.log
44+
```
45+
46+
## PARAMETERS
47+
48+
### -DifferenceCommandHelp
49+
50+
The CommandHelp object to compare against the reference object.
51+
52+
```yaml
53+
Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp
54+
DefaultValue: ''
55+
SupportsWildcards: false
56+
ParameterValue: []
57+
Aliases: []
58+
ParameterSets:
59+
- Name: (All)
60+
Position: 1
61+
IsRequired: true
62+
ValueFromPipeline: false
63+
ValueFromPipelineByPropertyName: true
64+
ValueFromRemainingArguments: false
65+
DontShow: false
66+
AcceptedValues: []
67+
HelpMessage: ''
68+
```
69+
70+
### -PropertyNamesToExclude
71+
72+
A list of one or more property names to exclude from the comparison.
73+
74+
```yaml
75+
Type: System.String[]
76+
DefaultValue: ''
77+
SupportsWildcards: false
78+
ParameterValue: []
79+
Aliases: []
80+
ParameterSets:
81+
- Name: (All)
82+
Position: Named
83+
IsRequired: false
84+
ValueFromPipeline: false
85+
ValueFromPipelineByPropertyName: false
86+
ValueFromRemainingArguments: false
87+
DontShow: false
88+
AcceptedValues: []
89+
HelpMessage: ''
90+
```
91+
92+
### -ReferenceCommandHelp
93+
94+
The base CommandHelp object to be compared to the difference object.
95+
96+
```yaml
97+
Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp
98+
DefaultValue: ''
99+
SupportsWildcards: false
100+
ParameterValue: []
101+
Aliases: []
102+
ParameterSets:
103+
- Name: (All)
104+
Position: 0
105+
IsRequired: true
106+
ValueFromPipeline: false
107+
ValueFromPipelineByPropertyName: true
108+
ValueFromRemainingArguments: false
109+
DontShow: false
110+
AcceptedValues: []
111+
HelpMessage: ''
112+
```
113+
114+
### CommonParameters
115+
116+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
117+
-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
118+
-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
119+
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
120+
121+
## INPUTS
122+
123+
### Microsoft.PowerShell.PlatyPS.Model.CommandHelp
124+
125+
## OUTPUTS
126+
127+
### System.String
128+
129+
## NOTES
130+
131+
## RELATED LINKS
132+
133+
- [Import-MarkdownHelp](Import-MarkdownHelp.md)
134+
- [Import-YamlCommandHelp](Import-YamlCommandHelp.md)

0 commit comments

Comments
 (0)