M2HTML tutorial

Download m2html.zip on this website and unpack it into a directory, say C:\matlab (could be /home/login/Documents/MATLAB/ as well or anything else).

Start MATLAB and add m2html in your MATLAB path:

>> addpath C:\matlab\m2html

Change directory into the directory just before m2html's one (here C:\matlab):

>> cd  C:\matlab

Never forget that m2html must always be launched one (or several) directory above the directory your wanting to generate documentation for (so, in that case, not from D:\ or C:\matlab\mytools).

m2html syntax is simple and consists of a list of parameter/value pair.

Let's generate a simple HTML documentation of m2html.

>> m2html('mfiles','m2html', 'htmldir','doc');

There are here two parameters (mfiles and htmldir) which are specified. This will parse the two M-files in the m2html directory (C:\matlab\m2html) and will create the corresponding HTML documentation in a doc directory (C:\matlab\doc). You can then have access to it on your web browser at this URL <file://C:\matlab\doc\index.html>.

In our case, there are other M-files in subdirectories, so let's specify with the parameter recursive that we want m2html to walk recursively into the directories under C:\matlab\m2html:

>> m2html('mfiles','m2html', 'htmldir','doc', 'recursive','on');

Cross-references are performed separately in each directory. If we want to have cross-references among separate directories, one needs to set the global directory to on:

>> m2html('mfiles','m2html', 'htmldir','doc', 'recursive','on', 'global','on');

Then you should notice that the cross-references for the m2html function (for example) have grown up (links to subdirectories). However note that this option may significantly slow down the parsing on huge toolboxes, and is then set to off by default.

There are many other options for m2html, see the help for a list:

>> help m2html

Let's see some of them. One of the key features of m2html is the fact that you can fully customize the output layout, thanks to the use of HTML templates (*.tpl files in C:\matlab\m2html\templates\*). You can modify them as you want to fit your needs. At this moment, two templates are provided: the default one (blue) and a frame one. Let's use the frame version (you need to delete a previously generated documentation, see after).

>> m2html('mfiles','m2html', 'htmldir','doc', 'recursive','on', 'global','on', 
          'template','frame', 'index','menu');

This template has a a singularity: you also need to modify the basename of the HTML index files (we chose menu here, index is now the frame file). Also note that when you use a template, all of its elements (images, CSS files, ...) are copied to the output directory if they are not present. So when you change the template, you'd better delete a previous generated HTML documentation. So to make the previous example work, you need to delete the C:\matlab\doc folder before.

Now let's build graph dependencies. To do that, you need to install the dot tool from GraphViz. Then you can set the graph option to on:

>> m2html('mfiles','m2html', 'htmldir','doc', 'recursive','on', 'global','on', 
          'template','frame', 'index','menu', 'graph','on');

The HTML output should look like this. Here is a dependency graph of the whole m2html toolbox.

This tutorial is over, it should work in the same way with your own MATLAB toolboxes. Please also read the README file provided with this toolbox and contact me by email if you have a specific question.