Recently I’ve had several users and customers ask me about auto-generating documentation from source code comments. I talked to the some of the engineers here at MindTouch and I was informed of a tool that they developed a while back named mindtouch.doc. Indeed, our DReAM framework documentation was created by this tool.
We’re making mindtouch.doc available for free as open source. It’s basically a much better alternative to Javadoc or similar doc generation tools. The auto-generated doc output can be pushed directly into your MindTouch or you can produce a MindTouch Archive (mtarc) and import this to your MindTouch site. I’m told it supports all the C# compiler supported tags for documentation comments.
<BEGIN repost of Arne’s original blog post>
If you write .NET code consumed by others, you are undoubtedly familiar with the inline XML documentation markup available. It’s a fairly simple embedded documentation syntax for which Visual Studio even provides some Intellisense and compile time checking. It keeps documentation and signature meta-data that can be derived from the code separate to avoid drift between code and documentation as much as possible.
Most developers initially start using it to provide Intellisense support for their code. But sooner or later most will want to publish the documentation as a reference document for their APIs. This would seem like the ideal use case of the mark-up format, but once you starting looking at the available tools, most developers find them lacking. Originally, NDoc provided the equivalent documentation generation that javadoc provides to developers on the Java side. Unfortunately NDoc was discontinued before .NET 2.0. In its place there exist Microsoft’s Sandcastle and mono’s monodoc. And now mindtouch.doc has been added to that list.
The goal of mindtouch.doc was to generate hierarchical reference documentation that could easily be imported into an MindTouch install. Unlike the standalone documentation generated by other tools, documentation imported into MindTouch can be easily extended by the extensive authoring and curation capabilities of MindTouch, such as IDF. Instead of just statically generated reference documentation, documentation in MindTouch can be tagged, linked, mashed-up with all your other documentation, tutorials, etc., including the ability to involve your community in the further growth of your documentation.
Authoring
We created mindtouch.doc to generate documentation for the DReAM Framework to be hosted on developer.mindtouch.com. The first task was to document all public classes in the framework using the .NET Xml comment docs:
With this in place, Visual Studio generates an XML document containing the meta-data from those comments. Using mindtouch.doc.exe, the code Assemblies along with their Documentation XML were converted into MindTouch import archives and imported into the site to produce documentation like this:
You can take a look at the MindTouch DReAM reference documentation to explore the entire generated documentation.
In addition to generating individual pages for each class, separate pages with Constructor, Property, Method and Event details are generates as child pages, along with Table of Content pages by Namespace and Assembly.
mindtouch.doc can generate documentation for an unlimited number of Assemblies at once. When the code to be documented is analyzed any references to any any class or member mentioned in the same or another assembly generates links between the relevant pages.
Since all content is imported as pages into MindTouch, you also get full revision history of past documentation imports (if the content has changed), so that documentation of newly added classes just requires a fresh import on top of the existing documentation.
Importing .NET documentation
If you want to try out the process, but don’t have documented code handy, you can import the DReAM documentation into your own MindTouch instance with the following command:
mindtouch.doc.exe -h mydomain.com -I ref/Dream mindtouch.dream.dll mindtouch.core.dll
This will prompt you for your user and password and import the documentation in ref/Dream.
The generated documentation has an external dependency on a template called DocToc. The purpose of this template is to allow simple Table of content customization using DekiScript and to make it easy to include custom css for documentation pages. The generated documentation HTML uses minimal markup along with classes to provide the greatest customization flexibility. The version of DocToc we use on developer.mindtouch.com simply looks like this:
<table style="background-color:#F9F9F9; border:1px solid #AAAAAA; font-size:95%; padding:5px;">
<tbody>
<tr>
<td>
<div align="center"><strong>Table of Contents</strong></div>
{{ page.toc }}
</td>
</tr>
</tbody>
</table>
Shipping your documentation
mindtouch.doc allows to directly import the generated documentation or to save the generated output as a MindTouch archive (.mtarc) which you can provide to customers to import into their own MindTouch installs. This is a regular MindTouch archive, the same that you would use to package up other documentation, scripts and templates authored in MindTouch. It can be imported via the Desktop Adapter ormindtouch.import.exe.
Documentation generation tool details
Running mindtouch.doc.exe without any arguments produces the following help output:
MindTouch Documentation, Copyright (c) 2010 MindTouch Inc.
USAGE: mindtouch.doc.exe [options] [assembly1 .. assemblyN]
Options:
(Options must be prefixed by a '-' or '/')
General:
?|usage - display this message
h|host <host> - MindTouch host (assumes standard API location)
u|uri <api-uri> - specify the full uri to the API (instead of using <host>)
I|importreltopath <path> - relative uri path for import
importrelto <id> - relative page id for import (alternative to importreltopath)
o|output - output path for generated documentation (will skip import)
R|retries - Maximum number of retries on import/export item failures (default: 3)
Authentication:
(if no authentication is provided, the program will prompt for user and password interactively)
A|authtoken <token> - authtoken to use for user authentication
U|user <username> - username for authentication (requires password option
P|password <password> - password for username authentcation
mindtouch.doc offers an easy way to take your documented .NET APIs and publish them with the power of MindTouch, no separate runtime or site required.
</ END repost of Arne’s original blog post>
Useful related resources:
- Arne’s original blog post from Oct 2010
- Sample docs that were auto-generated created from mindtouch.doc
- mindtouch.doc home page
- mindtouch.doc dll and source code
Autogenerate Docs from Source code. Hello mindtouch.doc; Goodbye NDoc, Javadoc…
Recently I’ve had several users and customers ask me about auto-generating documentation from source code comments. I talked to the some of the engineers here at MindTouch and I was informed of a tool that they developed a while back named mindtouch.doc. Indeed, our DReAM framework documentation was created by this tool.
We’re making mindtouch.doc available for free as open source. It’s basically a much better alternative to Javadoc or similar doc generation tools. The auto-generated doc output can be pushed directly into your MindTouch or you can produce a MindTouch Archive (mtarc) and import this to your MindTouch site. I’m told it supports all the C# compiler supported tags for documentation comments.
<BEGIN repost of Arne’s original blog post>
Most developers initially start using it to provide Intellisense support for their code. But sooner or later most will want to publish the documentation as a reference document for their APIs. This would seem like the ideal use case of the mark-up format, but once you starting looking at the available tools, most developers find them lacking. Originally, NDoc provided the equivalent documentation generation that javadoc provides to developers on the Java side. Unfortunately NDoc was discontinued before .NET 2.0. In its place there exist Microsoft’s Sandcastle and mono’s monodoc. And now mindtouch.doc has been added to that list.
The goal of mindtouch.doc was to generate hierarchical reference documentation that could easily be imported into an MindTouch install. Unlike the standalone documentation generated by other tools, documentation imported into MindTouch can be easily extended by the extensive authoring and curation capabilities of MindTouch, such as IDF. Instead of just statically generated reference documentation, documentation in MindTouch can be tagged, linked, mashed-up with all your other documentation, tutorials, etc., including the ability to involve your community in the further growth of your documentation.
Authoring
We created mindtouch.doc to generate documentation for the DReAM Framework to be hosted on developer.mindtouch.com. The first task was to document all public classes in the framework using the .NET Xml comment docs:
With this in place, Visual Studio generates an XML document containing the meta-data from those comments. Using mindtouch.doc.exe, the code Assemblies along with their Documentation XML were converted into MindTouch import archives and imported into the site to produce documentation like this:
You can take a look at the MindTouch DReAM reference documentation to explore the entire generated documentation.
In addition to generating individual pages for each class, separate pages with Constructor, Property, Method and Event details are generates as child pages, along with Table of Content pages by Namespace and Assembly.
mindtouch.doc can generate documentation for an unlimited number of Assemblies at once. When the code to be documented is analyzed any references to any any class or member mentioned in the same or another assembly generates links between the relevant pages.
Since all content is imported as pages into MindTouch, you also get full revision history of past documentation imports (if the content has changed), so that documentation of newly added classes just requires a fresh import on top of the existing documentation.
Importing .NET documentation
If you want to try out the process, but don’t have documented code handy, you can import the DReAM documentation into your own MindTouch instance with the following command:
This will prompt you for your user and password and import the documentation in ref/Dream.
The generated documentation has an external dependency on a template called DocToc. The purpose of this template is to allow simple Table of content customization using DekiScript and to make it easy to include custom css for documentation pages. The generated documentation HTML uses minimal markup along with classes to provide the greatest customization flexibility. The version of DocToc we use on developer.mindtouch.com simply looks like this:
<table style="background-color:#F9F9F9; border:1px solid #AAAAAA; font-size:95%; padding:5px;"> <tbody> <tr> <td> <div align="center"><strong>Table of Contents</strong></div> {{ page.toc }} </td> </tr> </tbody> </table>Shipping your documentation
mindtouch.doc allows to directly import the generated documentation or to save the generated output as a MindTouch archive (.mtarc) which you can provide to customers to import into their own MindTouch installs. This is a regular MindTouch archive, the same that you would use to package up other documentation, scripts and templates authored in MindTouch. It can be imported via the Desktop Adapter ormindtouch.import.exe.
Documentation generation tool details
Running mindtouch.doc.exe without any arguments produces the following help output:
mindtouch.doc offers an easy way to take your documented .NET APIs and publish them with the power of MindTouch, no separate runtime or site required.
</ END repost of Arne’s original blog post>
Useful related resources: