Documentation Generator / Sample App Integration

[michael-hawker]

Fixes #5, #21

Just starting a PR here with the in progress documentation changes.

Have the Source Generator modified to spit out the documentation index. Need to start working on the Sample App shell changes next.

Will dig into the sample app view Monday.

Copied the TODO table over from my last comment:

• We'll need to use AdditionalTextsProvider in the source generators to detect Markdown files as the primary source
  • Use YamlDotNet to parse the front-matter for the title/description and extra category metadata we have there for samples. Use that as the primary tree. Can't use YamlDotNet yet -> see Generators - analyzer using references causing problems CS8785 dotnet/roslyn#43903
  • Seach for the special 'sample id' tags in the document so we can link the sample attribute ids to the sample tree here.
  • This lets us have multiple sample pages with multiple samples. We may want to detect samples without a parent so in the experimental view we can mark them as (unreferenced) in their tab or something.
  • We'll effectively have a tree of the main sample pages by category/sub-category, and their children will be the referenced samples on those pages, this also let's us create a quick-sample jump in the right-hand sidebar we'll add later like the Controls Gallery has.
• Since WASM doesn't have the best Markdown support with our MarkdownTextBlock we can either, special case a solution for it, or use this same solution on all platforms for now:
  • pre-parse/break apart the Markdown file around the special sample tags
  • Then we use individual markdowntextblocks to display the markdown interspersed with the samples in the collection as part of a giant stackpanel/itemscontrol thing in a ScrollViewer
  • leverage @nickrandolph's markdown solution using marked.js from here for WASM for the individual blurbs CommunityToolkit/MVVM-Samples@911b355

• Detect if running in Experimental solution or all solution
  • If in experimental, use a TabView only as main navigation and have each sample and doc in it's own tab (this makes it easier to focus/test individual samples), docs would provide the full page as a preview of how it'll look in the main sample app
  • If all, we of course use the Navigation View with the full XAML Controls Gallery type setup.

(Will clean-up Markdown parsing to display across UWP/WinAppSDK/WASM as a separate PR, everything else on the list is complete.)

We should just decide if we want to test WASM here first after #88 goes in, or vice-versa.

[michael-hawker]

Dependent on #83 and #37

[michael-hawker]

I'll rebase this in the morning and try and add a fix for WinUI 3 as I hit microsoft/microsoft-ui-xaml#5315

I'm going to suggest once @Arlodotexe has a PR for the WASM fix for #37 (so I can test this on WASM as well), that we snap this PR in and leave making the Markdown pretty (the rest of the TODO list here) as another PR.

[michael-hawker]

PR should be all ready to go now! Tested in VS Code for WASM in the experiment level, as well as VS with UWP/WinUI 3 and with the all solution generated:

Now documentation files are the main source for driving the sample apps, and we have the sample pages embedded in them (with quick jump navigation as well).

When running in the experiment mode you get a broken out Tab View with each individual sample page and then the doc page as you would see in the main sample app.

More work can be done later still to improve the design/aesthetics of the sample app itself of course, but this is all the source generator infrastructure and UI back-bone required.

[michael-hawker]

@Arlodotexe we'll see what happens with the partial class comment in the CI, but otherwise everything should be good here, addressed all your feedback and opened new issues for tracking other bits. Let me know if that all looks good to you.

[michael-hawker]

Did a rebase to clean-up the history a bit, will merge this in with the history when the CI finishes again.