MatlabDocMaker.m

Go to the documentation of this file.

/* (Autoinserted by mtoc++)
 * This source code has been filtered by the mtoc++ executable,
 * which generates code that can be processed by the doxygen documentation tool.
 *
 * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler.
 * Except for the comments, the function bodies of your M-file functions are untouched.
 * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce
 * attached source files that are highly readable by humans.
 *
 * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to
 * the correct locations in the source code browser.
 * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files.
 */

class MatlabDocMaker {
    public: /* ( Constant ) */

        static const .char DOXYFILE_TEMPLATE = "Doxyfile.template";
        static const .char LATEXEXTRAS_TEMPLATE = "latexextras.template";
        static const .char MTOCPP_CONFIGFILE = "mtocpp.conf";
    public: /* ( Static ) */ /* ( Constant ) */

        static function charname = getProjectName() {

            name = " KerMor ";
        }
        /* %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     *% End of user defined part.
     *%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% */
    
    public: /* ( Static, Sealed ) */ /* ( Constant ) */

        static function chardir = getOutputDirectory() {
            dir = MatlabDocMaker.getPref(" outdir ");
        }
        static function chardir = getSourceDirectory() {
            dir = MatlabDocMaker.getPref(" srcdir ");
        }
        static function chardir = getConfigDirectory() {
            dir = MatlabDocMaker.getPref(" confdir ");
        }
        static function chardesc = getProjectDescription() {
            desc =  MatlabDocMaker.getPref(" proj_desc ", );
        }
        static function  setProjectDescription(char value) {
            if ~ischar(value)
                error(" The description must be a char array. ");
            end
            MatlabDocMaker.setPref(" proj_desc ", value);
        }
        static function charversion = getProjectVersion() {
            version = MatlabDocMaker.getPref(" proj_ver ", " 0 ");
        }
        static function  setProjectVersion(char value) {
            if ~ischar(value)
                error(" The project version must be a char array. ");
            end
            MatlabDocMaker.setPref(" proj_ver ", value);
        }
        static function fullPath = getProjectLogo() {
            logoFile = MatlabDocMaker.getPref(" proj_logo ",);
            fullPath = ;
            if ~isempty(logoFile)
                if isempty(fileparts(logoFile))
                    fullPath = fullfile(MatlabDocMaker.getConfigDirectory,logoFile);
                else
                    fullPath = logoFile;
                end
                if exist(fullPath," file ") ~= 2
                    warning(" MatlabDocMaker:getLogo ",[" Could not find logo file '%s'.\n "...
                        " No logo will be shown in documentation output. "],logoFile);
                end
            end
        }
        static function  setProjectLogo(char value) {
            if nargin < 1
                [f, p] = uigetfile(" *.* ", " Select project logo ", pwd);
                if f ~= 0
                    value = fullfile(p,f);
                else
                    fprintf(2," No file selected. Aborting.\n ");
                    return;
                end
            end
            if ~ischar(value)
                error(" The project logo file must be a char array. ");
            end
            if ~isempty(value)
                fullPath = value;
                if isempty(fileparts(value))
                    fullPath = fullfile(MatlabDocMaker.getConfigDirectory, value);
                end
                if ~exist(fullPath," file ")
                    error(" Invalid logo file: Could not find '%s' ",fullPath);
                end
            end
            MatlabDocMaker.setPref(" proj_logo ", value);
        }
    public: /* ( Static ) */ /* ( Constant ) */


        static function  open() {
            index = fullfile(MatlabDocMaker.getOutputDirectory, " index.html ");
            if ispc
                winopen(index);
            else
                [s, m] = system(sprintf(" xdg-open '%s' ",index));
                if s ~= 0
                    fprintf(2," Could not find/execute xdg-open: %s ",m);
                    web(index);
                end
            end
        }
        static function  create(varargin) {

            /* % Preparations */
            
            ip.addParamValue('open',false,@islogical);
            ip.addParamValue('latex',false,@islogical);
            ip.parse(varargin[:]);
            genlatex = ip.Results.latex;

            /*  Check for correct setup */
            cdir = MatlabDocMaker.getConfigDirectory;
            srcdir = MatlabDocMaker.getSourceDirectory;
            outdir = MatlabDocMaker.getOutputDirectory;
            /*  Check if doxygen config file template exists */
            doxyfile_in = fullfile(cdir,MatlabDocMaker.DOXYFILE_TEMPLATE);
            if exist(doxyfile_in," file ") ~= 2
                error(" No doxygen configuration file template found at '%s' ",doxyfile_in);
            end

            lstr = ;
            if genlatex
                lstr = " (+Latex) ";
            end
            fprintf([" Starting creation of doxygen/mtoc++ powered HTML%s documentation for '%s' (%s)\n "...
                " Sources: %s\nOutput to: <a href='matlab:MatlabDocMaker.open'>%s</a>\nCreating config files... "],lstr,...
                MatlabDocMaker.getProjectName,MatlabDocMaker.getProjectVersion,...
                srcdir,outdir);

            /*  Operation-system dependent strings */
            strs = struct;
            if isunix
                strs.null= " /dev/null ";
                strs.silencer= ;
            elseif ispc
                strs.null= " NUL ";
                strs.silencer= " @ "; /*  argh that took a while to remember.. */

            else
                error(" Current platform not supported. ");
            end

            /*  Save current working dir and change into the KerMor home
             * directory; only from there all classes and packages are
             * detected properly. */
            curdir = pwd;
            cd(srcdir);

            /*  Append the configuration file directory to the current PATH */
            pathadd = [pathsep cdir];
            setenv(" PATH ",[getenv(" PATH ") pathadd]);

            mtoc_conf = fullfile(cdir,MatlabDocMaker.MTOCPP_CONFIGFILE);
            filter = sprintf(" %smtocpp ",strs.silencer);
            if exist(mtoc_conf," file ")
                if isunix
                    strs.filter= " mtocpp_filter.sh ";
                    strs.farg= " $1 ";
                elseif ispc
                    strs.filter= " mtocpp_filter.bat ";
                    strs.farg= " %1 ";
                else
                    error(" Current platform not supported. ");
                end
                /* % Creation part */
                cdir = MatlabDocMaker.getConfigDirectory;
                /*  Create "configured" filter script for inclusion in doxygen  */
                filter = fullfile(cdir,strs.filter);
                f = fopen(filter," w ");
                fprintf(f," %smtocpp %s %s ",strs.silencer,strs.farg,mtoc_conf);
                fclose(f);
                if isunix
                    unix([" chmod +x  " filter]);
                end
            end

            /* % Prepare placeholders in the Doxyfile template */
            cdirfwd = strrep(cdir," \ "," / ");
            m = [" _OutputDir_ " strrep(outdir," \ "," \\ "); ...
                 " _SourceDir_ " strrep(MatlabDocMaker.getSourceDirectory," \ "," \\ ");...
                 " _ConfDir_ " strrep(cdir," \ "," \\ ");...
                 " _ConfDirFwdSlash_ " cdirfwd;...
                 " _ProjectName_ " MatlabDocMaker.getProjectName; ...
                 " _ProjectDescription_ " MatlabDocMaker.getProjectDescription; ...
                 " _ProjectLogo_ " strrep(MatlabDocMaker.getProjectLogo," \ "," \\ "); ...
                 " _ProjectVersion_ " MatlabDocMaker.getProjectVersion; ...
                 " _MTOCFILTER_ " strrep(filter," \ "," \\ "); ...
                 " _FileSep_ " filesep
                 ];

            /*  Check for latex extra stuff */
            texin = fullfile(cdir,MatlabDocMaker.LATEXEXTRAS_TEMPLATE);
            latexextras = ;
            if exist(texin," file ") == 2  
                latexstr = strrep(fileread(texin)," _ConfDir_ ",cdir);
                latexstr = strrep(latexstr," _ConfDirFwdSlash_ ",cdirfwd);
                latexextras = fullfile(cdir," latexextras.sty ");
                fid = fopen(latexextras," w+ "); fprintf(fid," %s ",latexstr); fclose(fid);
            end
            /*  Always use "/" for latex usepackage commands, so replace "\" (effectively windows
             * only) by "/", and dont pass the extension ".sty" as latex automatically adds it. */
            m(end+1,:) = [" _LatexExtras_ " strrep(latexextras(1:end-4)," \ "," / ")];
            L = " NO ";
            if genlatex
                L = " YES ";
            end
            m(end+1,:) = [" _GenLatex_ ",L];

            /*  Check how to set the HAVE_DOT flag */
            [s, ~] = system(" dot -V ");
            if s == 0
                HD = " YES ";
            else
                HD = " NO ";
                fprintf(" no 'dot' found... ");
            end
            m(end+1,:) = [" _HaveDot_ ",HD];

            /*  Read, replace & write doxygen config file */
            doxyfile = fullfile(cdir," Doxyfile ");
            doxyconfstr = regexprep(fileread(doxyfile_in),m(:,1),m(:,2));
            fid = fopen(doxyfile," w "); fprintf(fid," %s ",doxyconfstr); fclose(fid);

            /*  Fix for unix systems where the MatLab installation uses older
             * GLIBSTD libraries than doxygen/mtoc++ */
            ldpath = ;
            if isunix
                ldpath = " LD_LIBRARY_PATH=  ";
            end
            /*  Call doxygen */
            fprintf(" running doxygen with mtoc++ filter... ");
            [~,warn] = system(sprintf(" %sdoxygen '%s' 1>%s ",ldpath, doxyfile, strs.null));

            /*  Postprocess */
            fprintf(" running mtoc++ postprocessor... ");
            [~,postwarn] = system(sprintf(" %smtocpp_post '%s' 1>%s ",ldpath,...
                outdir, strs.null));
            if ~isempty(postwarn)
                warn = [warn sprintf(" mtoc++ postprocessor messages:\n ") postwarn];
            end

            /*  Create latex document if desired */
            if genlatex
                oldd = pwd;
                latexerr = false;
                latexdir = fullfile(outdir," latex ");
                if exist(latexdir," dir ") == 7
                    if exist(fullfile(latexdir," refman.tex ")," file ") == 2
                        fprintf(" compiling LaTeX output... ");
                        cd(latexdir);
                        [s, latexmsg] = system(" make ");
                        if s ~= 0
                            warn = [warn sprintf(" LaTeX compiler output:\n ") latexmsg];
                            latexerr = true;
                        end
                    else
                        fprintf(" cannot compile LaTeX output: no refman.tex found... ");
                    end
                end
                cd(oldd);
            end

            /*  Tidy up */
            fprintf(" cleaning up... ");
            if isfield(strs," filter ")
                delete(filter);
            end
            if ~isempty(latexextras)
                delete(latexextras);
            end
            delete(doxyfile);

            /* % Post generation phase  */
            cd(curdir);
            /*  Restore PATH to previous value */
            curpath = getenv(" PATH ");
            setenv(" PATH ",curpath(1:end-length(pathadd)));
            fprintf(" done!\n ");

            /*  Process warnings */
            showchars = 800;
            warn = strtrim(warn);
            if ~isempty(warn)
                dispwarn = [warn(1:min(showchars,length(warn))) "  [...] "];
                fprintf(" First %d characters of warnings generated during documentation creation:\n%s\n ",showchars,dispwarn);
                /*  Write to log file */
                log = fullfile(outdir," warnings.log ");
                f = fopen(log," w "); fprintf(f," %s ",warn); fclose(f);
                fprintf(2," MatlabDocMaker finished with warnings!\n ");
                fprintf(" Complete log file at <a href='matlab:edit( "" %s "" )'>%s</a>.\n ",log,log);
                /*  Check for latex log file */
                log = fullfile(outdir," _formulas.log ");
                if exist(log," file ")
                    fprintf(" Found LaTeX formula log file. Check <a href='matlab:edit( "" %s "" )'>%s</a> for any errors.\n ",log,log);
                end
                /*  Check for errors on latex generation */
                if genlatex && latexerr
                    log = fullfile(latexdir," refman.log ");
                    fprintf(" There have been errors with LaTeX compilation. See log file at <a href='matlab:edit( "" %s "" )'>%s</a>.\n ",log,log);
                end
            else
                fprintf(" MatlabDocMaker finished with no warnings!\n ");
            end

            /*  Open index.html if wanted */
            if ip.Results.open
                MatlabDocMaker.open;
            end
        }
        static function  setup() {

            /* % Validity checks */
            fprintf(" <<<< Welcome to the MatlabDocMaker setup for your project '%s'! >>>>\n ",MatlabDocMaker.getProjectName);

            /* % Setup directories
             * Source directory */
            srcdir = MatlabDocMaker.getPref(" srcdir ",);
            word = " keep ";
            if isstruct(srcdir) || isempty(srcdir) || exist(srcdir," dir ") ~= 7
                srcdir = pwd;
                word = " set ";
            end
            str = sprintf(" Do you want to %s %s as your projects source directory?\n(Y)es/(N)o?:  ",word,strrep(srcdir," \ "," \\ "));
            ds = lower(input(str," s "));
            if isequal(ds," n ")
                d = uigetdir(srcdir," Please select the projects source directory ");
                if d == 0
                    error(" No source directory specified. Aborting setup. ");
                end
                srcdir = d;
            end
            MatlabDocMaker.setPref(" srcdir ",srcdir);

            /*  Config directory */
            confdir = MatlabDocMaker.getPref(" confdir ",);
            word = " keep ";
            if isstruct(confdir) || isempty(confdir) || exist(confdir," dir ") ~= 7
                confdir = fullfile(srcdir," documentation ");
                word = " set ";
            end
            str = sprintf(" Do you want to %s %s as your documentation configuration files directory?\n(Y)es/(N)o?:  ",word,strrep(confdir," \ "," \\ "));
            ds = lower(input(str," s "));
            if isequal(ds," n ")
                d = uigetdir(confdir," Please select the documentation configuration directory ");
                if d == 0
                    error(" No documentation configuration directory specified. Aborting setup. ");
                end
                confdir = d;
            end
            MatlabDocMaker.setPref(" confdir ",confdir);

            /*  Output directory */
            outdir = MatlabDocMaker.getPref(" outdir ",);
            word = " keep ";
            if isstruct(outdir) || isempty(outdir) || exist(outdir," dir ") ~= 7
                outdir = confdir;
                word = " set ";
            end
            str = sprintf(" Do you want to %s %s as your documentation output directory?\n(Y)es/(N)o?:  ",word,strrep(outdir," \ "," \\ "));
            ds = lower(input(str," s "));
            if isequal(ds," n ")
                d = uigetdir(outdir," Please select the documentation output directory ");
                if d == 0
                    error(" No documentation output directory specified. Aborting setup. ");
                end
                outdir = d;
            end
            MatlabDocMaker.setPref(" outdir ",outdir);

            /* % Additional Project properties */
            if isequal(lower(input([" Do you want to specify further project details?\n "...
                    " You can set them later using provided set methods. (Y)es/(N)o?:  "]," s "))," y ")
                MatlabDocMaker.setPref(" proj_ver ",input(" Please specify the project version, e.g. '0.1':  "," s "));
                MatlabDocMaker.setPref(" proj_desc ",input(" Please specify a short project description:  "," s "));
                MatlabDocMaker.setProjectLogo;
            end

            /* % Check for necessary and recommended tools */
            hasall = true;
            setenv(" PATH ",[getenv(" PATH ") pathsep confdir]);
            fprintf(" [Required] Checking for doxygen...  ");
            [st, vers] = system(" doxygen --version ");
            if st == 0
                fprintf("  found %s\n ",vers(1:end-1));
            else
                fprintf(2,"  not found!\n ");
                hasall = false;                
            end
            fprintf(" [Required] Checking for mtoc++...  ");
            ldpath = ;
            if isunix
                ldpath = " LD_LIBRARY_PATH=  ";
            end
            [st, vers] = system(sprintf(" %smtocpp --version ",ldpath));
            if st == 0
                fprintf("  found %s\n ",vers(1:end-1));
            else
                fprintf(2,"  not found!\n ");
                hasall = false;
            end
            fprintf(" [Recommended] Checking for dot...  ");
            [st, vers] = system(" dot -V ");
            if st == 0
                fprintf("  found %s\n ",vers(1:end-1));
            else
                fprintf(2," dot Graphviz tool not found!\nInstall dot for nicer class diagrams.\n ");
            end
            fprintf(" [Recommended] Checking for latex...  ");
            [st, vers] = system(" latex --version ");
            if st == 0
                fprintf("  found %s\n ",vers(1:strfind(vers,sprintf(" \n "))-1));
            else
                fprintf(2," latex not found!\nA LaTeX installation available on the system path is strongly recommended with mtoc++.\n ");
            end
            /*  Ghostscript */
            fprintf(" [Recommended] Checking for ghostscript...  ");
            if ispc
                [st, vers] = system(" gswin32c --version ");
                if st ~= 0
                    [st, vers] = system(" gswin64c --version ");
                end
            else
                [st, vers] = system(" gs --version ");
            end
            if st == 0
                fprintf("  found %s\n ",vers(1:strfind(vers,sprintf(" \n "))-1));
            else
                fprintf(2," ghostscript not found!\nCreating LaTeX formulas might not work properly.\n ");
            end

            if ~hasall
                fprintf(2," Please make sure all prerequisites can be found on PATH or copy the executables into %s.\n ",confdir);
                fprintf(" <<<< MatlabDocMaker setup finished with warnings. >>>>\n ");
            else
                fprintf(" <<<< MatlabDocMaker setup successful. >>>>\nYou can now create your projects documentation by running <a href='matlab:MatlabDocMaker.create( "" open "" ,true)'>MatlabDocMaker.create</a>!\n ");
            end
        }
    private: /* ( Static ) */ /* ( Constant ) */

        static function value = getProjPrefTag() {
            str = regexprep(strrep(strtrim(MatlabDocMaker.getProjectName),"   "," _ ")," [^\d\w] ",);
            value = sprintf(" MatlabDocMaker_on_%s ",str);
        }
        static function value = getPref(name,default) {
            if nargin < 2
                def = [];
            else 
                def = default;
            end
            value = getpref(MatlabDocMaker.getProjPrefTag,name,def);
            if nargin < 2 && isempty(value)
                error(" MatlabDocMaker preferences not found/set correctly. (Re-)Run the MatlabDocMaker.setup method. ");
            end
        }


        static function value = setPref(name,value) {
            setpref(MatlabDocMaker.getProjPrefTag,name,value);
        }


};