m2html.m

M2HTML by itself generates an HTML documentation of Matlab M-files in the current directory.

function m2html(varargin)
%M2HTML - Documentation System for Matlab M-files in HTML
%  M2HTML by itself generates an HTML documentation of Matlab M-files in the
%  current directory. HTML files are also written in the current directory.
%  M2HTML('PropertyName1',PropertyValue1,'PropertyName2',PropertyValue2,...)
%  sets multiple option values. The list of option names and default values is:
%    o mFiles - Cell array of strings or character array containing the
%       list of M-files and/or directories of M-files for which an HTML
%       documentation will be built [ '.' ]
%    o htmlDir - Top level directory for generated HTML files [ '.' ]
%    o recursive - Process subdirectories [ on | {off} ]
%    o source - Include Matlab source code in the HTML documentation
%                               [ {on} | off ]
%    o syntaxHighlighting - Syntax Highlighting [ {on} | off ]
%    o tabs - Replace '\t' (horizontal tab) in source code by n white space
%        characters [ 0 ... {4} ... n ]
%    o globalHypertextLinks - Hypertext links among separate Matlab 
%        directories [ on | {off} ]
%    o todo - Create a TODO file in each directory summarizing all the
%        '% TODO %' lines found in Matlab code [ on | {off}]
%    o graph - Compute a dependency graph using GraphViz [ on | {off}]
%        'dot' required, see <http://www.research.att.com/sw/tools/graphviz/>
%    o indexFile - Basename of the HTML index file [ 'index' ]
%    o extension - Extension of generated HTML files [ '.html' ]
%    o template - HTML template name to use [ 'blue' ]
%    o save - Save current state after M-files parsing in 'm2html.mat' 
%        in directory htmlDir [ on | {off}]
%    o load - Load a previously saved '.mat' M2HTML state to generate HTML 
%        files once again with possibly other options [ <none> ]
%    o verbose - Verbose mode [ {on} | off ]
%
%  Examples:
%    >> m2html('mfiles','matlab', 'htmldir','doc');
%    >> m2html('mfiles',{'matlab/signal' 'matlab/image'}, 'htmldir','doc');
%    >> m2html('mfiles','matlab', 'htmldir','doc', 'recursive','on');
%    >> m2html('mfiles','mytoolbox', 'htmldir','doc', 'source','off');
%    >> m2html('mfiles','matlab', 'htmldir','doc', 'global','on');
%    >> m2html( ... , 'template','frame', 'index','menu');
%
%  See also HIGHLIGHT, MDOT, TEMPLATE.

%  Copyright (C) 2003 Guillaume Flandin <[e-mail]>
%  $Revision: 1.2 $Date: 2003/31/08 17:25:20 $

%  This program is free software; you can redistribute it and/or
%  modify it under the terms of the GNU General Public License
%  as published by the Free Software Foundation; either version 2
%  of the License, or any later version.
% 
%  This program is distributed in the hope that it will be useful,
%  but WITHOUT ANY WARRANTY; without even the implied warranty of
%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%  GNU General Public License for more details.
% 
%  You should have received a copy of the GNU General Public License
%  along with this program; if not, write to the Free Software
%  Foundation Inc, 59 Temple Pl. - Suite 330, Boston, MA 02111-1307, USA.

%  Suggestions for improvement and fixes are always welcome, although no
%  guarantee is made whether and when they will be implemented.
%  Send requests to [e-mail]

%  For tips on how to write Matlab code, see:
%     * MATLAB Programming Style Guidelines, by R. Johnson:
%       <http://www.datatool.com/prod02.htm>
%     * For tips on creating help for your m-files 'type help.m'.
%     * Matlab documentation on M-file Programming:
%  <http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_prog/ch10_pr9.shtml>

%  This function uses the Template class so that you can fully customize 
%  the output. You can modify .tpl files in templates/blue/ or create new
%  templates in a new directory.
%  See the template class documentation for more details.
%  <http://www.madic.org/download/matlab/template/>

%  Latest information on M2HTML is available on the web through:
%  <http://www.artefact.tk/software/matlab/m2html/>

%  Other Matlab to HTML converters available on the web:
%  1/ mat2html.pl, J.C. Kantor, in Perl, 1995: 
%     <http://fresh.t-systems-sfr.com/unix/src/www/mat2html>
%  2/ htmltools, B. Alsberg, in Matlab, 1997:
%     <http://www.mathworks.com/matlabcentral/fileexchange/loadFile.do?objectId=175>
%  3/ mtree2html2001, H. Pohlheim, in Perl, 1996, 2001:
%     <http://www.pohlheim.com/perl_main.html#matlabdocu>
%  4/ MatlabToHTML, T. Kristjansson, binary, 2001:
%     <http://www.psi.utoronto.ca/~trausti/MatlabToHTML/MatlabToHTML.html>
%  5/ Highlight, G. Flandin, in Matlab, 2003:
%     <http://www.madic.org/download/matlab/highlight/>
%  6/ mdoc, P. Brinkmann, in Matlab, 2003:
%     <http://www.math.uiuc.edu/~brinkman/software/mdoc/>
%  7/ Ocamaweb, Miriad Technologies, in Ocaml, 2002:
%     <http://ocamaweb.sourceforge.net/>
%  8/ Matdoc, M. Kaminsky, in Perl, 2003:
%     <http://www.mathworks.com/matlabcentral/fileexchange/loadFile.do?objectId=3498>
%  9/ Matlab itself, The Mathworks Inc, with HELPWIN and DOC

%-------------------------------------------------------------------------------
%- Set up options and default parameters
%-------------------------------------------------------------------------------
msgInvalidPair = 'Bad value for argument: ''%s''';

options = struct('verbose', 1,...
				 'mFiles', {{'.'}},...
				 'htmlDir', '.',...
				 'recursive', 0,...
				 'source', 1,...
				 'syntaxHighlighting', 1,...
				 'tabs', 4,...
				 'globalHypertextLinks', 0,...
				 'graph', 0,...
				 'todo', 0,...
				 'load', 0,...
				 'save', 0,...
				 'search', 0,...
				 'indexFile', 'index',...
				 'extension', '.html',...
				 'template', 'blue');

if nargin == 1 & isstruct(varargin{1})
	paramlist = [ fieldnames(varargin{1}) ...
				  struct2cell(varargin{1}) ]';
	paramlist = { paramlist{:} };
else
	if mod(nargin,2)
		error('Invalid parameter/value pair arguments.');
	end
	paramlist = varargin;
end

optionsnames = lower(fieldnames(options));
for i=1:2:length(paramlist)
	pname = paramlist{i};
	pvalue = paramlist{i+1};
	ind = strmatch(lower(pname),optionsnames);
	if isempty(ind)
		error(['Invalid parameter: ''' pname '''.']);
	elseif length(ind) > 1
		error(['Ambiguous parameter: ''' pname '''.']);
	end
	switch(optionsnames{ind})
		case 'verbose'
			if strcmpi(pvalue,'on')
				options.verbose = 1;
			elseif strcmpi(pvalue,'off')
				options.verbose = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'mfiles'
			if iscellstr(pvalue)
				options.mFiles = pvalue;
			elseif ischar(pvalue)
				options.mFiles = cellstr(pvalue);
			else
				error(sprintf(msgInvalidPair,pname));
			end
			options.load = 0;
		case 'htmldir'
			if ischar(pvalue)
				if isempty(pvalue),
					options.htmlDir = '.';
				else
					options.htmlDir = pvalue;
				end
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'recursive'
			if strcmpi(pvalue,'on')
				options.recursive = 1;
			elseif strcmpi(pvalue,'off')
				options.recursive = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
			options.load = 0;
		case 'source'
			if strcmpi(pvalue,'on')
				options.source = 1;
			elseif strcmpi(pvalue,'off')
				options.source = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'syntaxhighlighting'
			if strcmpi(pvalue,'on')
				options.syntaxHighlighting = 1;
			elseif strcmpi(pvalue,'off')
				options.syntaxHighlighting = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'tabs'
			if pvalue >= 0
				options.tabs = pvalue;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'globalhypertextlinks'
			if strcmpi(pvalue,'on')
				options.globalHypertextLinks = 1;
			elseif strcmpi(pvalue,'off')
				options.globalHypertextLinks = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
			options.load = 0;
		case 'graph'
			if strcmpi(pvalue,'on')
				options.graph = 1;
			elseif strcmpi(pvalue,'off')
				options.graph = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'todo'
			if strcmpi(pvalue,'on')
				options.todo = 1;
			elseif strcmpi(pvalue,'off')
				options.todo = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'load'
			if ischar(pvalue)
				try
					load(pvalue);
				catch
					error(sprintf('Unable to load %s.',pvalue));
				end
				options.load = 1;
				[dummy options.template] = fileparts(options.template);
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'save'
			if strcmpi(pvalue,'on')
				options.save = 1;
			elseif strcmpi(pvalue,'off')
				options.save = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'search'
			if strcmpi(pvalue,'on')
				options.search = 1;
			elseif strcmpi(pvalue,'off')
				options.search = 0;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'indexfile'
			if ischar(pvalue)
				options.indexFile = pvalue;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'extension'
			if ischar(pvalue) & pvalue(1) == '.'
				options.extension = pvalue;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		case 'template'
			if ischar(pvalue)
				options.template = pvalue;
			else
				error(sprintf(msgInvalidPair,pname));
			end
		otherwise
			error(['Invalid parameter: ''' pname '''.']);
	end
end

%-------------------------------------------------------------------------------
%- Get template files location
%-------------------------------------------------------------------------------
s = fileparts(which(mfilename));
options.template = fullfile(s,'templates',options.template);
if exist(options.template) ~= 7
	error('[Template] Unknown template.');
end

%-------------------------------------------------------------------------------
%- Get list of M-files
%-------------------------------------------------------------------------------
if ~options.load
	mfiles = getmfiles(options.mFiles,{},options.recursive);
	if ~length(mfiles), fprintf('Nothing to be done.\n'); return; end
	if options.verbose,
		fprintf('Found %d M-files.\n',length(mfiles));
	end
	mfiles = sort(mfiles); % sort list of M-files in dictionary order
end

%-------------------------------------------------------------------------------
%- Get list of (unique) directories and (unique) names
%-------------------------------------------------------------------------------
if ~options.load
	mdirs = {};
	names = {};
	for i=1:length(mfiles)
		[mdirs{i}, names{i}] = fileparts(mfiles{i});
		if isempty(mdirs{i}), mdirs{i} = '.'; end
	end

	mdir = unique(mdirs);
	if options.verbose,
		fprintf('Found %d unique Matlab directories.\n',length(mdir));
	end

	name = names;
	%name = unique(names); % output is sorted
	%if options.verbose,
	%	fprintf('Found %d unique Matlab files.\n',length(name));
	%end
end

%-------------------------------------------------------------------------------
%- Create output directory, if necessary
%-------------------------------------------------------------------------------
if isempty(dir(options.htmlDir))										       
	%- Create the top level output directory							       
	if options.verbose  												       
		fprintf('Creating directory %s...\n',options.htmlDir);  		       
	end 																       
	if options.htmlDir(end) == filesep, 								       
		options.htmlDir(end) = [];  									       
	end 																       
	[pathdir, namedir] = fileparts(options.htmlDir);					       
	if isempty(pathdir) 												       
		[status, msg] = mkdir(namedir); 								       
	else																       
		[status, msg] = mkdir(pathdir, namedir);						       
	end 																       
	if ~status, error(msg); end 														       
end 																	       

%-------------------------------------------------------------------------------
%- Get synopsis, H1 line, script/function, subroutines, cross-references, todo
%-------------------------------------------------------------------------------
if ~options.load
	synopsis   = cell(size(mfiles));
	h1line     = cell(size(mfiles));
	subroutine = cell(size(mfiles));
	hrefs      = sparse(length(mfiles),length(mfiles));
	todo       = struct('mfile',[],'line',[],'comment',{{}});
	ismex      = zeros(length(mfiles),length(mexexts));

	for i=1:length(mfiles)
		s = mfileparse(mfiles{i}, mdirs, names, options);
		synopsis{i}   = s.synopsis;
		h1line{i}     = s.h1line;
		subroutine{i} = s.subroutine;
		hrefs(i,:)    = s.hrefs;
		todo.mfile    = [todo.mfile repmat(i,1,length(s.todo.line))];
		todo.line     = [todo.line s.todo.line];
		todo.comment  = {todo.comment{:} s.todo.comment{:}};
		ismex(i,:)    = s.ismex;
	end
	hrefs = hrefs > 0;
end

%-------------------------------------------------------------------------------
%- Save M-filenames and cross-references for further analysis
%-------------------------------------------------------------------------------
matfilesave = 'm2html.mat';

if options.save