Get DocFX documentation online

[stakx]

Continuing from #1086.

• Basic DocFX setup for API documentation generation. (API filters, link to .NET FCL API documentation)
• Automate generation & deployment of DocFX site. (CI, or GitHub Actions?)
• Minimal customization. (Start page, icon, etc.)
• Figure out whether to use override files, and what for. (Consider extracting examples from source code files' XML doc into override files. We may want to keep XML doc brief & to the point and move more detailed info into external documentation.)
• Figure out whether & how to integrate the quickstart guide / info from the GitHub wiki.
• Replace NuDoq hyperlink in README.md.

[kzu]

FYI, checkout how I'm running docfx from CI at https://github.com/dotnetconfig/dotnet-config/blob/dev/.github/workflows/pages.yml which generates the site at http://dotnetconfig.org/

[maxalmonte14]

How can I contribute to solve this issue? I'm not a .NET expert but I would like to get involved.

[stakx]

I'm honestly not so sure anymore that DocFX is the right way to go. It's a fine tool in theory, but everytime I touch it, I'm running into a bunch of annoying little problems that waste a lot of time to iron out.

At this point I am wondering whether it wouldn't be easiest to just keep a bunch of Markdown files in a docs/ folder right here at the GitHub repository... mostly for conceptual documentation.

What's the point of reproducing API reference docs online anyway when one already has VS' IntelliSense and the Object Browser window? About the only thing not shown there are examples, but those could go in docs/. (We could also link to FuGet for API docs, if that is really needed.)

[stakx]

We now have the docs/ directory of this repo published as a static website at https://www.moqthis.com/moq4/. It's based on Jekyll though (not DocFX).

The plan is to publish conceptual docs there; a user guide (possibly including the quickstart) first, and perhaps a developer guide later on.