Skip to content

Commit 300926e

Browse files
sdwheelersdwheeler
authored
Reorganize main branch contents (#761)
1 parent 38d819a commit 300926e

File tree

121 files changed

+1490
-21517
lines changed

Some content is hidden

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

121 files changed

+1490
-21517
lines changed

‎docs/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Contributing to platyPS
2+
3+
## Get the code
4+
5+
```
6+
git clone https://github.com/PowerShell/platyPS
7+
```
8+
9+
## Understand code layout
10+
11+
TBD
12+
13+
## Build
14+
15+
To build the whole project, use the `build.ps1` helper script. It depends on the
16+
[dotnet cli](https://docs.microsoft.com/en-us/dotnet/core/tools/) build tool.
17+
18+
On Windows you would also need to
19+
[install full dotnet framework](https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers)
20+
if it's not installed already.
21+
22+
```powershell
23+
.\build.ps1
24+
```
25+
26+
As part of the build, platyPS generates help for itself. The output of the build is placed in
27+
`out\Microsoft.PowerShell.PlatyPS`.
28+
29+
`build.ps1` also imports the module from `out\platyPS` and generates help itself.
30+
31+
> [!NOTE]
32+
> If you changed C# code, `build.ps1` will try to overwrite a DLL in use. You will then need to
33+
> re-open your PowerShell session. If you know a better workflow, please suggest it in the Issues.
34+
35+
## Tests
36+
37+
Each part of the project has a test set:
38+
39+
- The C# part has xUnit tests.
40+
- The PowerShell part has [Pester](https://github.com/pester/Pester) tests. You can run them with
41+
`Invoke-Pester`.
42+
43+
> [!NOTE]
44+
> Pester tests always force-import the module from the output location of `.\build.ps1`.
45+
46+
## Schema
47+
48+
If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss
49+
it.
50+
51+
## Repo structure
52+
53+
TBD

‎docs/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
ms.date: 10/22/2024
3+
---
4+
# Microsoft.PowerShell.PlatyPS design notes
5+
6+
## Design notes
7+
8+
### Features/Functionality
9+
10+
- When PlatyPS writes file output, it should create folder structure of module-named folders
11+
containing cmdlet markdown for the cmdlets in those modules
12+
- PlatyPS should populate the markdown with all the facts that it can reasonably gather about the
13+
command:
14+
- Name
15+
- Syntax of all parameter sets
16+
- Parameter names and metadata (type, all attributes, etc. arranged by parameter set)
17+
- Common parameters (if supported)
18+
- Input types - types that can be piped to the command
19+
- Output types - as defined by the cmdlet attributes
20+
- PlatyPS should insert placeholder text for all content that must be provided by the author
21+
22+
### Module notes
23+
24+
- Total rewrite in C# to improve performance, object model, and extensibility
25+
- Cmdlets are focused on the object model and provide a single purpose
26+
- Chain cmdlets in a pipeline to perform complex operations
27+
- Workflow style cmdlets will be script-based to improve usability for authors
28+
- Script-based provide readable code model that allows end-users to customize their own
29+
workflows as needed
30+
- Workflows are easier to code in script rather than in C#
31+
- Total breaking change from previous versions
32+
- New module name - Microsoft.PowerShell.PlatyPS
33+
- Allows you to install side-by-side with previous versions
34+
- No common cmdlet names between modules
35+
- No intent to provide proxies for old cmdlets
36+
- Cmdlet names better reflect what they do
37+
- Import-SomeFormat
38+
- Export-SomeFormat
39+
- New markdown parsing and rendering powered by markdig
40+
- Module provides Yaml output to be used by the Learn reference pipeline
41+
- Object model is the heart of the new module
42+
- Establishes a common object model for cmdlets and module files
43+
- Markdown is the source of truth for the documentation
44+
- Cmdlets import the markdown in the the CommandHelp object model
45+
- CommandHelp objects can be exported to Markdown, Yaml, or MAML
46+
- CommandHelp objects can be imported from Markdown, Yaml, or MAML
47+
- Conversion to/from MAML is lower fidelity other formats - results in loss of data and accuracy
48+
of the documentation
49+
50+
### Markdown notes
51+
52+
- Markdown is the source of truth for the documentation
53+
- Markdown has a strict H2/H3 structure
54+
- You can't add headers or reorder them
55+
- Not all H2/H3 sections require content. The H2/H3 line is required, but the content is optional.
56+
This is done to ensure that the markdown structure is consistent with the object model.
57+
- Metadata names have been changed to match PowerShell property names and common terminology.
58+
- This causes less confusion for authors and makes it easier to troubleshoot validation and
59+
rendering issues
60+
- Import command can read old (0.14) format or new format and converts Markdown into CommandHelp
61+
object
62+
- Export commands convert CommandHelp object into other formats
63+
- Export to markdown command can writes new markdown format
64+
- Export to Yaml is used by the Learn reference pipeline and reflects the new object model
65+
- Export to MAML is lower fidelity and results in loss of data and accuracy of the documentation
66+
due to limitation in Get-Help and the MAML specification
67+
- The Yaml frontmatter is used to store metadata that is not part of the markdown content
68+
- The object model has a set of required key/value pairs
69+
- The `document type` and `PlatyPS schema version` keys are inviolate (cannot be changed)
70+
- You can add custom metadata to the frontmatter
71+
- Any key/value pairs not managed by PlatyPS are passed through unaltered
72+
73+
### Authoring process
74+
75+
- Authoring is always a manual process requiring human intervention
76+
- PlatyPS helps automate the process and provides a consistent structure for the documentation but
77+
can't fill in descriptions, examples, or related links
78+
- PlatyPS inserts placeholder text to show you where to add content
79+
- Authors must review and edit the markdown files to ensure that the content is accurate for every
80+
authoring step
81+
- Creating new markdown for new modules/commands
82+
- Migrating existing markdown to the new format
83+
- Updating existing markdown based on new versions of modules/commands
84+
85+
### Converting to/from other formats
86+
87+
- Markdown is the source of truth for the documentation
88+
- Converting from the old Markdown format to the new format is a one-way process
89+
- The new format has more structure and metadata than the old format
90+
- The new format is more consistent and easier to validate
91+
- The old format does not reflect all of the correct facts about parameters
92+
- Converting from the old to the new format does not improve the accuracy of the parameter
93+
metadata; you must run the update process
94+
- The update process requires that the commands/modules be available in the current session so
95+
that the complete parameter metadata can be discovered
96+
- Converting to Yaml
97+
- There is no loss of fidelity when converting from the Markdown to Yaml (or vice versa)
98+
- The Yaml is just a serialization of the CommandHelp object model
99+
- All properties are preserved even if the value is null
100+
- Rendering to HTML should handle null values gracefully (e.g. conditional formatting to omit null
101+
values)
102+
- Converting to/from MAML
103+
- There is a loss of fidelity when converting to MAML due to limitations in the MAML specification
104+
and Get-Help cmdlet
105+
- Importing from MAML is supported as a method of last resort.
106+
107+
## Frontmatter
108+
109+
| FileType | v1 Key | v1 Status | v2 key | v2 Status |
110+
|----------|--------------------|-----------------------------------------------------|------------------------|----------------------------------------------------|
111+
| cmdlet | | n/a | document type | Required |
112+
| cmdlet | external help file | Required - unique to cmdlet | external help file | Required |
113+
| cmdlet | online version | Key required, value can be null - unique to cmdlet | HelpUri | Key required, value can be null - unique to cmdlet |
114+
| cmdlet | Locale | Required | Locale | Required |
115+
| cmdlet | Module Name | Key required, value can be null | Module Name | Key required, value can be null |
116+
| cmdlet | ms.date | Optional | ms.date | Optional |
117+
| cmdlet | schema | Required | PlatyPS schema version | Required |
118+
| cmdlet | title | Required | title | Required |
119+
| cmdlet | | n/a | aliases | Optional |
120+
| module | | n/a | document type | Required |
121+
| module | Help Version | Key required, value can be null - unique to module | Help Version | Key required, value can be null - unique to module |
122+
| module | Download Help Link | Key required, value can be null - unique to module | HelpInfoUri | Key required, value can be null - unique to module |
123+
| module | Locale | Required | Locale | Required |
124+
| module | Module Guid | Required - unique to module | Module Guid | Required - unique to module |
125+
| module | Module Name | Required | Module Name | Required |
126+
| module | ms.date | Optional | ms.date | Optional |
127+
| module | schema | Required | PlatyPS schema version | Required |
128+
| module | title | Required | title | Required |
129+
130+
## Scenarios to support OPS
131+
132+
1. Workflow script to convert all markdown files to YAML in a folder
133+
1. Workflow script for CabGen
134+
1. Make rendering decisions for HTML presentation
135+
136+
These items to be done by Sean and Jason working with DanniX and team.
137+
138+
## Future ideas
139+
140+
- Create a method to convert CommandHelp object to the Get-Help object model
141+
- This could be an easy way to ship markdown instead of MAML for downlevel systems that don't have
142+
or cant support Help v2.
143+
- Add commands to stream conversion to Markdown to support Markdown rendering in the console (e.g.
144+
pipe to `glow.exe`)
145+
- Create workflow convenience scripts to include in module
146+
- Compare-MarkdownCommandHelp - can't compare module files
147+

0 commit comments

Comments
 (0)