Merge pull request #796 from sdwheeler/sdw-w476169-main-docs

Update repo docs in main branch

Author: sdwheeler

CHANGELOG.md

@@ -0,0 +1,44 @@
+# Microsoft Open Source Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct][02].
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the
+  experience
+- Focusing on what's best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- Disruptive behavior
+  - Submitting spam comments, issues, or pull requests
+  - Defacing or vandalizing the project, repository, content, or documentation
+  - Intentionally introducing security vulnerabilities
+- Disrespectful behavior
+  - Trolling, insulting or derogatory comments, and personal or political attacks
+  - Public or private harassment
+  - Publishing others' private information, such as a physical or email address, without their
+    explicit permission
+  - The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Other conduct that could reasonably be considered inappropriate in a professional setting
+
+## Resources
+
+- [Microsoft Open Source Code of Conduct][02]
+- [Microsoft Code of Conduct FAQ][03]
+- Contact [opencode@microsoft.com][04] with questions or concerns
+- Employees can reach out at [aka.ms/opensource/moderation-support][01]
+
+<!--  link references -->
+[01]: https://aka.ms/opensource/moderation-support
+[02]: https://opensource.microsoft.com/codeofconduct/
+[03]: https://opensource.microsoft.com/codeofconduct/faq/
+[04]: mailto:opencode@microsoft.com

CODE_OF_CONDUCT.md

@@ -1,126 +1,45 @@
-# Contributing to platyPS
-
-## Get the code
-
-```
-git clone https://github.com/PowerShell/platyPS
-```
-
-## Understand code layout
-
-There are two parts:
-
-- `Markdown.MAML.dll`, a .NET library written in C#.
-  It does the heavy lifting, like parsing Markdown, transforming it into XML, and so on.
-  You can open `.\Markdown.MAML.sln` in Visual Studio on any platform.
-- A PowerShell module in `.\src\platyPS`.
-  This module provides the user CLI.
-
-## Build
-
-To build the whole project, use the `build.ps1` helper script.
-It depends on the [dotnet cli](https://docs.microsoft.com/en-us/dotnet/core/tools/) build tool.
-
-On Windows you would also need to [install full dotnet framework](https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers) if it's not installed already.
-
-```powershell
-.\build.ps1
-```
-As part of the build, platyPS generates help for itself.
-The output of the build is placed in `out\platyPS`.
-
-`build.ps1` also imports the module from `out\platyPS` and generates help itself.
-
-**Note**: if you changed C# code, `build.ps1` will try to overwrite a DLL in use.
-You will then need to re-open your PowerShell session.
-If you know a better workflow, please suggest it in the Issues.
-
-## Tests
-
-Each part of the project has a test set:
-
-- The C# part has xUnit tests.
-  You can run them from Visual Studio or from command line with `dotnet test ./test/Markdown.MAML.Test`.
-- The PowerShell part has [Pester](https://github.com/pester/Pester) tests.
-  You can run them with `Invoke-Pester`.
-
-**Note**: Pester tests always force-import the module from the output location of `.\build.ps1`.
-
-## Schema
-
-If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss it.
-
-## Repo structure
-
-- **src\platyPS** - sources to create the final PowerShell module.
-- **src\Markdown.MAML, Markdown.MAML.sln** - source code for C# Markdown to MAML converter.
-- **[platyPS.schema.md](platyPS.schema.md)** - description of Markdown that platyPS expects.
-
-## Data transformations
-
-Data transformations are the core of platyPS.
-A user has content in some form and she wants to transform it into another form.
-E.g. transform existing module help (in MAML) to Markdown and use it in the future to generate the external help (MAML) and static HTML for online references.
-
-platyPS provides APIs in the form of cmdlets for end-user scenarios.
-These scenarios are assembled from simple transformations.
-This chart describes these simple transformations:
-
-```
- +----------+
- |          |
- |   HTML   |
- |          |
- +------^---+
-        |
- +------+------------+           +-----------------+
- |                   |           |  Markdown Model |
- |  Markdown file    +----------->                 |
- |                   |           +-+---------------+
- |                   |             |
- +---------------^---+             |
-                 |                 |
-                 |                 |
-                 |                 |
-              +--+-----------------v--+
-              |      MAML Model       |
-              | (= Generic Help model)|
-              |                       |
-              +--+-------------------^+
-                 |                   |
-                 |                   |
-                 |                   |
-+----------------v-----+            ++--------------------------+
-|  MAML XML file       |            | Help Object in PowerShell |
-| (External help file) +------------> (+ Get-Command object)    |
-+----------------------+            +---------------------------+
-```
-
-### Example `New-MarkdownHelp`
-
-A user creates a platyPS Markdown for the first time with `New-MarkdownHelp`:
-
-```powershell
-New-MarkdownHelp -Command New-MyCommandHelp
-```
-
-Under the hood, the following tranformations happen:
-
-[MAML XML file] --> [Help Object + Get-Command object] --> [MAML Model] --> [Markdown file]
-
-# Making a new release
-
-1. Make sure that `CHANGELOG.md` is up-to-date, move section from `UNRELEASED` to new section `<release name>`.
-1. Make sure platyPS help itself (content in .\docs folder) is up to date. 
-   `Update-MarkdownHelp -Path .\docs` should result in no changes.
-1. Do not change the version in platyps.psd1. Git tag will update this version for release.
-1. From master, tag the release.
-1. Push tag to GitHub.
-1. Find the corresponding build on AppVeyor.
-1. Download ZIP archive with the module from Appveyor's Artifacts tab.
-1. Unblock the ZIP archive (`Unblock-File foo.zip`), and copy the ZIP's contents to `$env:PSMODULEPATH` so it's available to `Publish-Module`.
-1. Publish the module to the Gallery: `Publish-Module -RequiredVersion <version> -Verbose -NuGetApiKey $apiKey`.
-1. Check that https://www.powershellgallery.com/packages/platyPS/ updated.
-1. Publish a new github release from https://github.com/PowerShell/platyPS/releases to move "Latest release" label to the new tag.
-
-Congratulations! You just made a release.
+# Contributing to Microsoft.PowerShell.PlatyPS
+
+This project follow the [Microsoft Open Source Code of Conduct][02]. By participating in this
+project, you agree to abide by its terms.
+
+We welcome your contributions and suggestions.
+
+## Contributor License Agreement (CLA)
+
+Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you
+have the right to, and actually do, grant us the rights to use your contribution. For more
+information, see the [Microsoft CLA][03].
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA. If so, the bot will guide you through the process of signing the CLA.
+
+## Get started
+
+There are several ways to contribute to this project:
+
+- **Report issues**: If you find a bug, please open an issue using the appropriate
+  [issue template][06].
+- **Suggest features**: If you have an idea for a new feature or improvement, please start a
+  discussion in the [GitHub discussions][05]. When a feature request is approved, a maintainer will
+  convert the discussion into an issue that can be the basis for a pull request.
+- **Submit pull requests**: If you want to contribute code, please fork the repository and submit a
+  pull request. Pull requests should be based on the `main` branch and include a clear description
+  of the changes you are proposing. **Pull requests must be linked to an issue to be considered for
+  merging.**
+- **Contribute to documentation**: There are two kinds of documentation:
+  - **User documentation**: This is the documentation that provide cmdlet reference and usage
+    information. This documentation is published to [Microsoft Learn][07] and maintained in the
+    [MicrosoftDocs/PowerShell-Docs-Modules][04] repository.
+  - **Developer documentation**: This is the documentation aimed at contributors to the PlatyPS
+    project. It is stored in the `docs` folder of this repository. For more information, see the
+    [README][01] file in the `docs` folder.
+
+<!-- link references -->
+[01]: ./docs/README.md
+[02]: CODE_OF_CONDUCT.md
+[03]: https://cla.microsoft.com
+[04]: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules
+[05]: https://github.com/PowerShell/platyPS/discussions
+[06]: https://github.com/PowerShell/platyPS/issues/new
+[07]: https://learn.microsoft.com/powershell/module/microsoft.powershell.platyps/

CONTRIBUTING.md

@@ -1,115 +1,82 @@
-[![Build status](https://ci.appveyor.com/api/projects/status/u65tnar0cfkmqywl/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/markdown-maml/branch/master)
-[![Build status](https://travis-ci.org/PowerShell/platyPS.svg?branch=master)](https://travis-ci.org/PowerShell/platyPS/builds)
+# Microsoft.PowerShell.PlatyPS
 
-[![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)
+**PlatyPS** is the tool that Microsoft uses to create the PowerShell content you get from `Get-Help`
+and build the content published as [PowerShell documentation][03] on Microsoft Learn.
 
-# PlatyPS
+PowerShell help files are stored as [Microsoft Assistance Markup Language][05] (MAML), an XML
+format. **PlatyPS** simplifies the authoring process by allowing you to write the help files in
+Markdown, then convert to MAML. [Markdown][04] is widely used in the software industry,
+supported by many editors including **Visual Studio Code**, and easier to author.
 
-PlatyPS provides a way to:
+**Microsoft.PowerShell.PlatyPS** includes several improvements:
 
-* Write PowerShell External Help in Markdown
-* Generate markdown help ([example](docs/Update-MarkdownHelp.md)) for your existing modules
-* Keep markdown help up-to-date with your code
+- Re-write in C# leveraging [markdig][02] for parsing Markdown (the same library used by
+  Microsoft Learn to render Markdown)
+- Provides a more accurate description of a PowerShell cmdlet and its parameters and includes
+  information that was previously unavailable
+- Creates an object model of the help file that you can manipulate and supports chaining cmdlets for
+  complex operations
+- Increased performance - processes 1000s of Markdown files in seconds
 
-Markdown help docs can be generated from old external help files (also known as MAML-xml help), the command objects (reflection), or both.
+## Install Microsoft.PowerShell.PlatyPS
 
-PlatyPS can also generate cab files for [`Update-Help`](https://technet.microsoft.com/en-us/library/hh849720.aspx).
+PlatyPS runs on:
 
-## Why?
+- Windows PowerShell 5.1+
+- PowerShell 7+ on Windows, Linux, and macOS
 
-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.
-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.
-
-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.
-
-Markdown is designed to be human-readable, without rendering. This makes writing and editing easy and efficient. 
-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.
-
-## Common setups
-
-There are 2 common setups that are used:
-
-1. Use markdown as the source of truth and remove other types of help.
-2. Keep comment based help as the source of truth and periodically generate markdown for web-site publishing.
-
-They both have advantages and use-cases, you should decide what's right for you.
-There is slight preference toward number 1 (markdown as the source).
-
-## Quick start
-
-* Install platyPS module from the [PowerShell Gallery](https://powershellgallery.com):
+Install the module from [PSGallery][06].
 
 ```powershell
-Install-Module -Name platyPS -Scope CurrentUser
-Import-Module platyPS
+Install-PSResource -Name Microsoft.PowerShell.PlatyPS
 ```
 
-* Create initial Markdown help for `MyAwesomeModule` module:
+## Layout of this repository
 
-```powershell
-# you should have module imported in the session
-Import-Module MyAwesomeModule
-New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs
-```
+### Branches
 
-* Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content.
+- `main`: Contains the source code for the new version of PlatyPS named
+  **Microsoft.PowerShell.PlatyPS**. This is the current supported version of PlatyPS. You can find
+  this version listed as [Microsoft.PowerShell.PlatyPS][06] in the PowerShell Gallery.
+- `v1`: Contains the source code for the legacy version of PlatyPS named **platyPS**. This version
+  is no longer actively maintained, but it's available for reference and legacy support. The latest
+  version of this code is 0.14.2. You can find this version listed as [platyPS][07] in the
+  PowerShell Gallery.
 
-* Create external help from markdown help
+### Folder structure
 
-```powershell
-New-ExternalHelp .\docs -OutputPath en-US\
-```
+- `docs` - contains design documentation for the PlatyPS project
+- `src` - contains the source code for the module
+- `test` - contains the tests files used to validate the code at build time
+- `tools` - contains tools used to build the module
 
-* **Congratulations**, your help is now in markdown!
+## Contributing to the project
 
-* Now, if your module code changes, you can easily update your markdown help with
+If you are interested in contributing to the PlatyPS project, please see the
+[contribution guide][01].
 
-```powershell
-# re-import your module with latest changes
-Import-Module MyAwesomeModule -Force
-Update-MarkdownHelp .\docs
-```
+### Build the code
 
-### PlatyPS markdown schema
+Prerequisites for build:
 
-Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a **particular way**.
-We have defined a [**schema**](platyPS.schema.md) to determine how parameters are described, where scripts examples are shown, and so on.
+- PS7
+- .NET 8 SDK
 
-The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell. 
+Prerequisites for test:
 
-If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and `Update-MarkdownHelp`.
-You would not be able to generate extrenal help or update your markdown.
+- Pester 4.x (Pester 5.x is not supported)
 
-It may be fine for some scenarios, i.e. you want to have online-only version of markdown.
+To build the source code, run the following command in the root of the repository:
 
-## [Usage](docs)
-
-Supported scenarios:
-
-*  Create Markdown
-    *  Using existing external help files (MAML schema, XML).
-    *  Using reflection
-    *  Using reflection and existing internal external help files.
-    *  For a single cmdlet
-    *  For an entire module
-
-*  Update existing Markdown through reflection.
-
-*  Create a module page <ModuleName>.md with summary. It will also allow you to create updatable help cab.
-
-*  Retrieve markdown metadata from markdown file.
-
-*  Create external help xml files (MAML) from platyPS Markdown.
-
-*  Create external help file cab
-
-*  Preview help from generated maml file.
-
-## Remoting
-
-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.
-Just pass `-Session $Session` parameter to the platyPS cmdlets and it will do the rest.
-
-## Build
+```powershell
+.\build.ps1 -Clean
+```
 
-For information about building from sources and contributing see [contributing guidelines](CONTRIBUTING.md).
+<!-- link references -->
+[01]: ./CONTRIBUTING.md
+[02]: https://github.com/xoofx/markdig
+[03]: https://learn.microsoft.com/powershell/scripting
+[04]: https://wikipedia.org/wiki/Markdown
+[05]: https://wikipedia.org/wiki/Microsoft_Assistance_Markup_Language
+[06]: https://www.powershellgallery.com/packages/Microsoft.PowerShell.PlatyPS
+[07]: https://www.powershellgallery.com/packages/platyPS