Self-contained documentation for .NET projects - doxygen?

Question

The task

We'd like to maintain some developer's documentation for our .NET projects with the following criteria:

• "Documents", ideally written in Markdown for providing information that's not closely related to a piece of code (like overview, FAQ).
• Standard inline comments for code and API documentation. We do thus in form of standard inline (XML) comments on the classes/interfaces (primarily for IntelliSense support, secondarily for being able to generate an API reference) and would like to continue to do like that.
• The documentation is contained in what it documents; e.g. if it's an overview of a solution then in the solution, if it's for a project then among the project's files, version controlled in the same way as the code (this is so the docs are close to what they document, so they are less prone for going out of date, and also this was docs are always "at hand").
• Ability to auto-generate (from the CI server) a readable, compiled documentation for a whole project, including "documents" and inline comments for APIs.

An example

We've a project that's a component usable within a 3rd party system. For this project we have the following type of documentation:

• Overview (what the project does, what are the aims)
• Installation instructions
• API documentation
• Version history

We'd like to enable our developers and other developers to - read this documentation from the project's source package and - from a website.

Solutions we've looked at

• Using a wiki (we tried Confluence): this is good for "document"-type of documentation (like overview or installation notes), but it lives independently from the project itself. It's another system to maintain and because it's not before one's eyes when doing development it can quickly go out of date. Also it's one more task to somehow integrate auto-generated API documentation into it.
• Using Markdown files and storing them along the code: this is simple and documentation is always at hand and close to what it documents; however we somehow need to generate a publishable web package from these files and the source files' inline documentation.

So far doxygen looks like the solution capable of providing all these. Do you agree?

See "How to include custom files in doxygen".

Answer 1

Broadly speaking this is exactly what I am currently doing, and I'm using Doxygen.

However, I'm afraid I know nothing about .NET. The project I'm working on is a Java package, but includes API documentation extracted from the source, user guides, release records and things like deprecations.

The only thing out of our scope and in yours is Installation Guide, but that's really only because the developer only gets to read it after installation.

We have Jenkins CI building the document on every change.

The 'descriptive' text is all written in Markdown which Doxygen handles reasonably well.

Downsides: If you are familiar with the way Doxygen handles grouping of text for source code you may be confused that these commands don't work to group the blocks of text in Markdown. There are a few other specific oddities but you'll probably find most of them if you scan my own questions on the subject (here, here and here)

Upsides: (Things we've found useful that you've not mentioned)

1. We can also parse the 'doxygen' markup in the Java API to create a javadoc that IDE's such as Eclipse can use. This does mean we have to limit ourselves to javadoc-style command in the API docs but that's not a big limit.

2. We've included, under doxygen 'build switch', a manual for your developers on how to write the documentation for the manual (OK, this is slightly recursive!). This provides the recommended command subset to use, and whether (according to taste) you want people to use doxygen @subsection or Markdown ## for headings etc.

Hope that helps.

I'd suggest you try it; trialling a sample of each type of document section you need, to see if it will do the whole set of functions you need. Nothing more annoying documenting 90% then finding it won't do the last 10%.