DocMounter is a handy visual tool to document your .NET assemblies and produce HxS (MSHelp2) help solutions, HTML manuals and standard XML documentation files using the Sandcastle compiler. Very simple but effective, no need to learn special documentation languages such as MAML.
From the first versions of Visual Studio .NET, it has been possible to document your classes directly in code and create the standard documentation sections (such as the summary, remarks, parameter descriptions etc) which contain the standard tags. But for us, developers, it was quite inconvenient to fully document our classes and create such long sections as remarks directly in code. The situation is worse in the case when the documentation is created by a technical writer and the code is created by a developer; it is not quite appropriate for them to work with the same source files simultaneously.
Our company, 10Tec (http://www.10Tec.com
), also encountered all these problems while working on our first .NET component, iGrid grid control that acts like a fast and easy replacement for the standard .NET DataGrid control. We decided to solve them by creating our own tool and gave it a name "DocMounter". DocMounter became a tool to separate the code from the documentation without loss of the conveniences provided by Visual Studio, and even more. Step by step the tool was being improved, and finally it has become an easy-to-use application that can be useful for other developers. The actual version implements many useful features you cannot get from the standard VS XML documentation technique.
DocMounter allows you to perform the following tasks:
- Enter all the standard sections such as summary, remarks, example, see also, etc for classes and their members through its visual interface.
- Add standard XML documentation tags - such as see, code, list, table, etc - through a handy insert tag dialog.
- Create additional topics using the same syntax as for the classes and their members (XML documentation syntax).
- Manage the nodes of your project, i.e. the structure of the table of contents of the future help file.
- View and edit the source of your topics in an editor window that supports syntax highlighting, customizable spell checking and code folding.
- Create conceptual topics (which are not related to a particular class or its member) using the same syntax as for the classes and their members.
- Generate the standard XML documentation files which can be used in any tool and development environment that supports it (including all versions of Visual Studio .NET).
- Generate a single HTML file from all the additional topics. Later this file may be slightly edited and converted into a DOC, RTF, or PDF format and used as a manual.
- The internal extensible model of DocMounter allows to integrate external documentation compilers (such as NDoc or SandCastle) to produce the required output documentation.
Simplicity, Simplicity and Simplicity once more!
There are few open-source projects to build documentation, such as outdated NDoc and the modern SandCastle documentation compiler, but if you ever tried to use them you know how difficult to make them working for your practical needs. When we designed DocMounter, the simplicity was one of the main key features of the product, and now we have a wonderful tool you can use to build help solutions from the first minutes after deployment with one mouse click.
Despite its simplicity, DocMounter has the complete set of tools you can use to build full-featured XML documentation and help files. As we said, we are using it widely in our company to document our .NET products such as the iGrid.NET grid control. Many customers throughout the world also found this tool very useful for their projects.
DocMounter 2 and Sandcastle
This version of DocMounter uses a free open-source documentation compiler named Sandcastle which is used by the Microsoft team to create the MSDN library (also hosted on CodePlex at http://sandcastle.codeplex.com/
). This means that you will get the same look-and-feel HxS documentation like in MSDN used by Microsoft since the VS 2005 release.
Sandcastle is downloaded and configured separately as described in the manual, but our DocMounter package also contains small enhancements and corrections to the original Sandcastle installation to have better functionality and look in some places. All these enhancements are applied by DocMounter automatically during the build process, so you do not need to do something by hands for that.
To give you a general feeling of the product, let us tell you how to build your first HxS file with DocMounter in 5 minutes.
To document your .NET library, create a new project using the File\New project menu command. An open file dialog will be displayed – select the required assemblies in it. After you select one or several assemblies and click the "Open" button, the project will be created. You'll see that the topic tree contains all namespaces defined in your assemblies. Your project is ready for work – you can expand the nodes, select members and write descriptions for them in the right big editor pane:Click to see full image
Type in some descriptions for the members of your library. To build your project, just click the "Build & View HxS" button on the toolbar. Your first HxS file will be created and displayed in the Microsoft Document Explorer automatically in a minute. You'll see the complete log of the build process with all possible warnings and error messages in the "Output" pane opened at the bottom of the tool.
Main benefits of DocMounter
Let's list all the main benefits of the tool so you'll get the general feeling of what this tool can do and how it can save your time.
- The most important benefit of DocMounter is that your code and its description are in different places, so your code isn't bloated because of documentation in your source files (what you get in Visual Studio). This also allows two different people to work on the product development and its documentation at the same time independently (the developer and technical writer).
- Visual Studio does not allow you to create conceptual documentation as you can only document members in the source code files, but in DocMounter you can create this type of help topics.
- DocMounter allows you to build not only an interactive HxS file with a tree structure of conceptual topics, but also a printable manual in which all the conceptual topics are placed one-by-one.
- DocMounter produces the documentation of the same look-and-feel as you can see in MSDN.
- DocMounter has intuitive user interface and is very simple, but its features covers all the main functions and features you need to write help solutions.
- In DocMounter, you write both conceptual and member topics in one unified interface using the same principles and tag set. Instead of writing tags manually, DocMounter provides you with a handy visual "Tag Insert" dialog which saves your time a lot.
- Help topics are written practically as plain text in DocMounter's topic editor (you write only the useful contents), and they are automatically compiled into full-featured result help pages which uses the same visual and functional template.
- If members you are documenting have been changed (renamed, parameter list was changed, etc), DocMounter automatically updates the project to insert the updated members. All the outdated members aren't removed and can be easily found using a special search command. This allows you to copy the descriptions from the obsolete members into the new ones and remove the obsolete members from the project manually when you no longer need them.
- If you already documented your assemblies using the standard Visual Studio approach, DocMounter allows you to easily switch to DocMounter to continue your work in this tool. You can import all your member descriptions from the assemblies' accompanying XML comment files or even from the description attributes stored directly in your assemblies!
- Though DocMounter is based on the external Sandcastle help compiler and uses Microsoft's standard XML Documentation and SandCastle MAML languages to build help topics, it adds some cool additional features you couldn't have earlier. Among them are the abilities to insert pictures into member topics and make cross-reference links between member topics and conceptual topics.
And finally, DocMounter is totally free and you can get its full source code also for free!
We must admit that we would have never written the current version of DocMounter so good if we hadn't had a good text editor control. DocMounter 2.0 has a very handy topic editor based on the brilliant Editor.NET component provided by Quantum Whale (http://www.qwhale.net/
) for this project for free.
Due to this component, DocMounter allows us to edit the Xml-like source of our help topics using syntax highlighting and code folding. This great editor also gave us the ability to implement a built-in customizable spell checker, and now we are producing output files with much less typos and mistakes directly from DocMounter without checking spelling in an external editor like MS Word after compilation. Keep up the good work, the Quantum Whale development team!