Draft experiment: Docs via docfx

[SeanKilleen]

Inspired by discussion at nunit/docs#337

Exploring the option of generating world-class docs in a maintainable and welcoming way using docfx.

What other projects are using docfx?

• Akka.NET's docs are built using docfx.

Work Remaining

Wiki Content to Port:

• NUnit Docs
• NUnit Xamarin Runners
• VS Test Adapter
• VS Test Generator
• NUnit Analyzers
• Developer Info

As part of the initial effort:

• Get a docfx build going
• Generate API documentation for publicly documented NUnit API surface
• Allow browsing of multiple versions? (if docfx allows this well)
• Add contribution guide for docs
• Add readme for building docs
• Add logos etc. as appropriate.
• Check wiki references (e.g. links within [[ ]]) to point them to the right spot.
• Ensure all warnings are resolved
• Check wiki repo to ensure all content has migrated
• Breadcrumb navigation
• Add copyright / license to footer
• Add home page
• Check links for pointers to wiki and change to markdown references

Decisions to be made by NUnit team representatives:

• Decide where docs should live (whether to have this live at nunit/docs or somewhere other than in this folder.)
• Whether to include generated source code docs
• If there's an attribute name they'd like to use to hide certain code from docs publication
• Whether additional articles (e.g. VS test runner) should be captured in this site as well or done separately.
• Decide what to do about potential 404s (URLs will be changing)

Once those decisions have been made:

• Exclude any internal public methods using filter config and an attribute (maybe a new MeantForInternalConsumptionAttribute or something along those lines?)
• Generate docs for additional APIs outside of this repo?
• Update build to utilize console docs builder
• Update azure pipelines to build and push docs.
• Ensure wiki content changes since this PR are reflected in the new docs

Formatting after full contents have been ported:

• Ensure all pages have title frontmatter (for title bar)
• Ensure all pages have top headings (for web page -- use title if possible?)
• Call out info, warnings, cautions, etc. using docfx syntax
• Replace C# code snippet language with csharp
• Clean up the navigation
• Check alignment of code samples
• Pass for markdown linting

Potential follow-up issues to create:

• Consider SEO aspects
• Programmatic "See Also"? (vs text in individual files)
• Prettier, Jekyll-style URLs?
• Run html-proofer or similar to check for dead links and images
• Turn todos within wiki into actual issues in nunit/docs

How to build this PR

• Prerequisite: Install docfx (using chocolatey? choco install docfx -y)
• cd docs
• Run docfx build
• Run docfx serve and navigate to http://localhost:8080/_site

[SeanKilleen]

FYI @ChrisMaddock -- a decent amount of progress so far with not too much time invested.

[ChrisMaddock]

While I wait for the NUnit team's decision on where this content should live, I'll be continuing along with the rest of the plan -- doing cleanup, markdown linting, ensuring pages have front-matter to start with, adding a draft home page / contributing guide, etc.

Awesome! 🎉 Let's keep this moving, I'll comment back on the other issue. 😄

[SeanKilleen]

Closing this in favor of nunit/docs#339 -- please follow along with the adventure there!