verify and mdsnippets

[SimonCropp]

re SimonCropp/MarkdownSnippets#710

this PR represents how i would solve the problem.

So in effect this PR does

• use Verify to assert the output of the program.
• as a side effect we now have the output of a given console args in a snapshot file
• use that snapshot file as a snippet.

so this way when you change the output, you get to QA th output before accepting it. and the readme will be updated on the next build. The "updated on the next build" can be annoying if u forget to do a build before pushing a change. so i have added a GH action that will re run the docs to ensure they are always in sync.

List of all changes:

• pulled out common settings into a Directory.Build.props
• added a test project. i picked nunit. let me know if u want mstest or xunit
• added verify to that project.
• added tests for help and deprecate as mentioned above
• added an Upload Test Results step to the GH build. so that if Verify detects a mis-match in CI you will get the resulting files as assets. saves you trolling through the build log for the differences
• added a on-push-do-docs.yml action. as mentioned above
• ignore .idea/ since i like rider ;)
• added an mdsnippets config file with InPlaceOverwrite https://github.com/SimonCropp/MarkdownSnippets?tab=readme-ov-file#inplaceoverwrite That is usually the preferred option for smaller projects
• Moved to a non top level statement. so we can call it from a test

[joelverhagen]

Wow, this is amazing! Thank you for taking the time to put this together.

I'm wondering why you use UTs + Verify as a way to generate the content instead of something like https://www.nuget.org/packages/MarkdownSnippets.MsBuild/ which appears to fix up the snippets at build time. What are the drawbacks for doing the fix-up at build time vs. out of build with a GitHub commit or explicit CLI command?

Do you think some people would prefer to have every build in VS/Rider/CLI to fix up the docs? It seems more inuative to me but maybe I'm missing some pros/cons. The idea I have in my mind is that you wouldn't need to wait for the GitHub Actions auto-commit to come in, i.e. you could do the whole PR offline. I haven't tested it but it looks like your GitHub Action workflow will commit to the same branch so a PR would get a commit added to it automatically. Maybe that's good enough vs. having the PR author include the change in one of their own commits.

This approach makes sense if the repo owner wants the UTs as well. It's probably a good idea to have an acceptance test on generated help text.

[SimonCropp]

I'm wondering why you use UTs + Verify as a way to generate the content instead of something like https://www.nuget.org/packages/MarkdownSnippets.MsBuild/ which appears to fix up the snippets at build time. What are the drawbacks for doing the fix-up at build time vs. out of build with a GitHub commit or explicit CLI command?

this PR does also apply MarkdownSnippets.MsBuild. the CI is just a backup in case you change a snippets content, and forget to do a build before pushing. I have seen some people use an "after all tests hook" to execute mdsnippets via the programmatic API so content generated by tests will always be applied to markdown files

you use UTs + Verify as a way to generate the content instead of

it is not really "instead of". we always want two parts. 1. generate the content. 2. merge the content.

re 1. i like to use UTs + Verify to gen the content since, as a side effect, i get all the benefits of snapshot testing for my development flow. eg UI for testrunner, diffing tools when something has changed. etc. In many projects i use tests without Verify to create content to mdsnippets to find. eg this https://github.com/SimonCropp/Polyfill/blob/main/src/Tests/BuildApiTest.cs creates multiple include files. eg https://github.com/SimonCropp/Polyfill/blob/main/api_list.include.md

re 2. i always use have MarkdownSnippets.MsBuild + CI action in place. sometime if i am editing content outside of the IDE i also use the command line or the explorer extension https://github.com/SimonCropp/MarkdownSnippets?tab=readme-ov-file#add-to-windows-explorer.

[SimonCropp]

i should also point out sometimes it is not "generate the content". but instead the content is static. eg i often have a test that shows a simple usage of an api. i then wrap that in a region and include it in the docs md. so the code in docs are never out of date