Added build script for Microsoft Learn docs

[Arlodotexe]

This PR adds a new Build-Toolkit-Docs.ps1 build script that:

• Iterates all components in the toolkit
• Finds all markdown files for each component
• Transforms and outputs each markdown file to the specified directory:
  • Retrieves the title from YAML and inserts it as a Markdown header
  • Replaces sample placeholders with a code snippet reference.
  • Will display the sample code-behind directly in published docs.
• Builds and outputs a Docfx-compatible table-of-contents (TOC) to the specified directory:
  • The location of the transformed markdown file is inserted as the href.
  • If the markdown file name is the same as the component, it is renamed to index.md to avoid creating paths like /SettingsControls/SettingsControls/.
  • If there is only one markdown file for a component's samples, it is placed in the root of the TOC instead of a folder.
  • To avoid the need for a redirect if more docs are added, the folder is still present in the href, and the file is expected to be named index.md if it is the only doc for a component.

[michael-hawker]

I tried running in Labs and got this:

Oh, same on Windows repo as well:

I know I wrote this originally, what am I missing...? 🙈

I tried I:\code\WindowsToolkit\tooling> .\Build-Toolkit-Docs.ps1 ..\docs too, but that didn't work either.

[Arlodotexe]

Looks like a difference between PowerShell 5.1 and PowerShell Core.

Since this is only used by maintainers, let's get this merged and open a new ticket for fixing this to work in pwsh 5.1.

[michael-hawker]

@Arlodotexe thoughts on how hard it'd be to group things in the TOC under 'Controls' that have the Controls package/project name? I think that'd help reduce some of the noise in the TOC and make things easier to find?

Otherwise looks good, we'll just have to redirect the existing page duplicates that got renamed to index in the docs repo.

[Arlodotexe]

@Arlodotexe thoughts on how hard it'd be to group things in the TOC under 'Controls' that have the Controls package/project name? I think that'd help reduce some of the noise in the TOC and make things easier to find?

@michael-hawker Right now we're just iterating each of our components in the ./components directory to build the list. We still need to create a meta-package for Controls (see CommunityToolkit/Windows#115) but our infrastructure doesn't have an elegant way to account for toolkit-using-toolkit in general, a problem tangential to why we can't do nested components like ./components/Controls/Primitives/ or ./components/AppServices/AppServices.SourceGenerators/.

Our flattened ./components/ folder structure is our "component registry", while our tooling (build scripts, msbuild, props files, etc) strings components together based on that flat list.

Yes, it would be good to group things more here. But if we do that grouping here, it won't be a reflection of how things are actually structured in the toolkit and will be more work to migrate later, after the above work that we'll need to do anyway.

For now, I think it would be preferable to publish docs with the improvements we have here and come back when we've made improvements to our underlying infrastructure (including new redirects that would entail). It will be less confusing for contributors and people consuming our packages.

[michael-hawker]

Yeah, that make sense, I know there's still a lot of those things we're still working through.

I agree that we want some mapping to the structure of the packages, so I agree that I don't think we'd want to move any folders around for the docs or anything to make it more straight-forward to maintain.

The TOC is pretty flexible though and a separate entity, so I think some organization to better align to our sample app categorization could be handy, but that is indeed something we can investigate more later. Incremental improvements. :)