I'd like to propose a new way of documentation generation from C# source code and markdown files, which is used by .Net Core and ASP.NET right now. We call it Docfx internally and it will be open-sourced this month or next. Let me give you a brief introduction about What/How/Why.

docfx is an API documentation generator for .NET, currently support C# and VB, as similar to JSDoc or Sphinx. It has the ability to extract triple slash comments out from your source code. What's more, it has syntax to link additional files to API to add additional remarks. docfx will scan your source code and your additional conceptual files and generate a complete HTML documentation website for you. docfx provides the flexibility for you to customize the website through templates.

For short, it supports

• Generate an API reference site from the source code and comments.
• Allow you to write additional description, code samples for specific API/Method/Property in Markdown files.
• Allow you to write conceptual topics ( non-develop ) in Markdown and help you generate HTML output.
• Allow you to customize the layout using Liquid or Mustache, a template system similar to Jekyll.

As I mentioned above, .NET Core is powered by docfx already, you can visit Documentaion for guidelines or samples

and visit API Reference for source code documents.

You can also take a look at the source behind dotnet.github.io to get a rough idea about how it works, it's stored in https://github.com/dotnet/core-docs. Developers and common users can use the same repo to contribute documents, and the output site will be pushed back the gh-page branch of the source code repository. As the output is self-hosting static site, so you can put it in any server you like and it just works.

Please let me know if you are Okay with docfx or any question ?