Monodoc is a stable documentation system developed especially for mono and .NET. It started as a simple browser for published ECMA XML docs and soon grew to be a scalable documentation browser and editor.
The implementation of monodoc is very different from what most developers are familiar with. Rather than documentating in-code, documentation is included in an external xml file. This allows for interesting features like distributed documentation by all your developers. While the learning curve is slightly higher for this style of documentation, its benefits are well worth for projects of moderate sizes and larger.
Monodoc works by generating reference xml documents for .NET assemblies. This is done using System.Reflection to extract all the System.Type objects from the referencing assembly. Documentation for each System.Type is done in the xml document. To be viewed in monodoc, those xml documents must be prepared into monodoc format and added to the monodoc node list. The benefit of adding the documentation to monodoc is the use of monodoc's documentation editor.
Table Of ContentsBefore we can start building our documentation, we need to have an example project to work with. For the sake of simplicity, the standard HelloWorld console project is used. The following examples are shown in MonoDevelop, but any editor or IDE can be used.
The following is the code for Main.cs.
// project created on 11/28/2004 at 6:49 PM using System; namespace Example { public class MainClass { public static void Main(string[] args) { new HelloWorldApp( args ); } } public class HelloWorldApp { private string name; public HelloWorldApp( string [] args ) { this.Name = this.ArgsToName( args ); Console.WriteLine( "Hello, " + this.Name + "!" ); } public string Name { get { return name; } set { name = value; } } public string ArgsToName( string [] args ) { if ( args.Length < 1 ) return "Unknown"; string retval = ""; foreach( string arg in args ) { retval += arg + ((args.Length > 1) ? " " : ""); } return retval.Trim(); } } }
You can now build this project with MonoDevelop or
$ mcs -out:HelloWorld.exe -target:exe Main.cs
If you build your project with MonoDevelop that your output executable will bin in HelloWorld/bin/Debug/ by default.
With the newly generated executable, xml reference documents can be made. This is done with the following command.
$ monodoc --update HelloWorld.exe -o docs/
The --update switch of monodoc updates the reference xml documents with new information from the passed assembly. This will not override existing comments so it works well if your asseblies change often. The -o dirname option allows changing of the output directory. The default output directory is ./. The reference xml documents are created or updated in outputdir/Namespace/Type.xml
With our xml reference documents created, monodoc can be used once again to bundle the documents into something usable by the gui. To do this, the --assemble option is used. That will output a *.tree and *.zip file. In addition to this, we need to create a *.source file and modify the monodoc.index file. This will add our new documentation into the class browser.
First, lets bundle our documentation.
$ monodoc --assemble --out helloworld-docs docs/
This now gives us helloworld-docs.zip and helloworld-docs.tree. All that is left, is build our helloworld-docs.source file and copy the three files to the monodoc sources directory. The following is the contents of the helloworld-docs.source file we need to create.
<?xml version="1.0"?> <monodoc> <source provider="ecma" basefile="helloworld-docs" path="classlib-helloworld"/> </monodoc>
Lets now copy the documentation files to the monodoc sources directory and edit the monodoc.index file.
$ sudo cp helloworld-docs.{tree,zip,source} `monodoc --get-sourcesdir`
Add the following line to your monodoc.xml file found in the monodoc base directory. It should be added inside the outermost <node> tag.
<node label="HelloWorld Documentation" name="classlib-helloworld"/>
You should now have HelloWorld sample documentation inside of monodoc. This will make it simple to edit from within the monodoc gui. The following image shows what monodoc should look like.
Editing of documentation can be done within monodoc. While viewing your documentation from the previous chapter, look for [Edit] links. These links will take you to a form that allows you to update the documentation. The following images show you how to do this.
The changes that are made in monodoc are not immediately merged into the documentation you installed into the monodoc sources directory. To do this, we must merge the changes.
Table Of ContentsMerging documentation consists of binding the changes you have made in the editor to the XML reference documents. This can be done locally as well as remotely to the Mono Documentation Server. The remote server is used only for public projects such as Gtk#, Mono, and Gnome#. Once the documentation is merged, it can be distributed and seen just as you see it in Monodoc.
To merge changes we use the --merge-changes option to monodoc
on the command-line. It requires the change file created by monodoc and the
folder containing your reference xml documents. The change file can be found
at `~/.config/monodoc/changeset.xml'.
To merge our changes we made above with their reference xml documents, we will execute the following command.
$ monodoc --merge-changes ~/.config/monodoc/changeset.xml docs/
We can now build our documentation again so it can be distributed.
$ monodoc --assemble --out helloworld-docs docs/
You can re-install or distribute the contents of this just like previously done in chapter 2.4
Table Of ContentsMonodoc has come quite a long way. There are a few places that it can still be extended to aide development teams. A great improvement would be the support for a documentation server for individual projects not associated with Mono. This would allow for a project team to host a server and work on their documentation in a distributed and efficient manner. What monodoc does currently, it does very well. This includes building, editing, and merging documentation in a safe and efficient manner.
Table Of ContentsQ: I made changes to my source code! How do I update the reference documents?
A: You use the same command you used to create the documentation origonally. It
should only update the new additions to your reference document.
$ monodoc --update HelloWorld.exe -o docs/
Table Of ContentsDecember 13, 2004 - Christian Hergert
* Added summary, faq, and changelog chapters.
* Added css styling.
* New table of contents.
Table Of Contents