Docs Correlation

[michael-hawker]

What do we do for docs?

We should have a markdown file similar to that of what we use in the docs.microsoft.com template.

Should we have a 'feature' doc plus docs for each sample?

Can we correlate specific samples to specific pages?

[Arlodotexe]

similar to that of what we use in the docs.microsoft.com template.

@michael-hawker Know where I can find this?

[michael-hawker]

Sorry @Arlodotexe added a link here and above. It's in the docs repo.

I'm thinking it'll be cool eventually if we could have a Labs area in the toolkit docs and auto-submit changes to docs here into the docs repo or something (given that they should be PR reviewed for content still when added).

We also have a MarkdownRenderer for our Markdown control which understands the DocFX sections here: https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/main/Microsoft.Toolkit.Uwp.SampleApp/Controls/SampleAppMarkdownRenderer.cs

I was thinking we could extend this and come up with a method for instantiating a sample page as a component within the document so we could have a richer experience when viewing the full-samples app compared to the playground area of an individual experiment.

e.g.

In an experiment you'd see the individual samples to navigate to each page, and if you looked at the docs you'd have links to jump/navigate to that page:

But in the all-samples app when you click on the experiment, it'd bring up the documentation page with the samples embedded directly (like the XAML Controls Gallery does):

We can investigate being fancier later about exposing properties or having live xaml editing in the rich experience later like we do in our sample app today. But hopefully the above shows direction of where these experiences differ between editing/creating and playground?

[Arlodotexe]

Actually, taking inspiration from the XAML Control Gallery sounds like a wonderful idea.

The XAML Control Gallery has a multiple samples per control, where each sample has

1. A visible sample
2. Title and description
3. XAML / C# that can be copied
4. (Optionally) options that can be toggled for the current sample, that also update the copy-able code.

Maybe we look at doing something like this?
If we still feel like we need it, we can add live-editing of XAML to samples down the road.

[Arlodotexe]

For docs, do we want it to be inline like the current toolkit, or would it be better to link to the most up-to-date docs on docs.microsoft.com, like the control gallery does? Keep in mind we may be running this on the web already

[michael-hawker]

Writing down some notes here before the weekend, I'll audit this list and move to the top of the issue on Monday:

• 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.
  • 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.

Think later when we get to CommunityToolkit/WindowsCommunityToolkit#3200 we could actually try and account and use a similar approach if it works well here to try and provide more complex rendering solutions/options? Anyway, that's a future thing, just wanted to call it out, as I think the above would be a novel/interim solution that can do well for us.