ita_generate_helpOverview.m 12.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
function ita_generate_helpOverview(folder)
%ITA_GENERATE_HELPOVERVIEW - Generate Toolbox Help
%  This function automatically generates html/xml files for the Matlab Help
%  Browser (apps.html, classes.html, index_demos.html, helptoc.xml)
%
%   See also help, doc, helpdesk, ita_toolbox_setup, ita_generate_documentation.
%
%   Reference page in Help browser
%        <a href="matlab:doc ita_generate_helpOverview">doc ita_generate_helpOverview</a>

% <ITA-Toolbox>
% This file is part of the application HTMLhelp for the ITA-Toolbox. All rights reserved.
% You can find the license for this m-file in the application folder.
% </ITA-Toolbox>


% Author: Jonas Tumbrgel -- Email: jonas.tumbraegel@akustik.rwth-aachen.de
% Created:  18-May-2012

%% Help Browser->link Demos (helptoc.xml/index_demo.html changed by this code)
% - Tumbrgel 05/2012
% This part looks for avaliable 'ita_tutorial_____.m Files and links them
% into Matlab Help Browser (doc) as demo in "RWTH ITA Toolbox"
% 1. open helptoc.xml and look for insertion point with ita_openHTML
% helptoc.xml generates RWTH ITA Toolbox menu-point in MATLAB Help Browser
% 2. open index.html and look for insertion point with ita_openHTML
% 3. looks for avaliable tutorials in Toolbox Folder (tutorials)
% 4. Generate helptoc.xml and index_demo.html->link existing tutorials
Marco Berzborn's avatar
Marco Berzborn committed
29
%%
30
% 1. ....
Marco Berzborn's avatar
Marco Berzborn committed
31 32 33 34 35
oldfolder = pwd;
[~, toolboxFolderName] = fileparts(folder);
templateFolder = fullfile(ita_toolbox_path, 'applications', 'HTMLhelp', 'templates');
htmlFolder = fullfile(folder, 'HTML');
[helpXML_begin, helpXML_end] = ita_openHTML(fullfile(templateFolder, 'template_helptoc.xml'));
36 37

% 2. ....
Marco Berzborn's avatar
Marco Berzborn committed
38 39
[index_demoHTML_begin, index_demoHTML_end] = ita_openHTML(fullfile(templateFolder, 'template_index_demos.html'));

40 41 42 43 44
% 3. ....
cd(folder);
tutFiles = rdir(['**' filesep 'ita_tutorial*.m']); %search for tutorial files

% 4. ....
Marco Berzborn's avatar
Marco Berzborn committed
45 46
helpXML = helpXML_begin; %now build a new helptoc.xml
index_demoHTML = index_demoHTML_begin; %now build a new index_demo.html
47 48 49 50 51 52 53 54
idxApp=1;
appDemo=[];
for idx = 1:length(tutFiles)
    if length(tutFiles(idx).name)>16
        if strcmp(tutFiles(idx).name(end-16:end),'compileDocument.m') %do not generate html help for those
            continue
        end
    end
Marco Berzborn's avatar
Marco Berzborn committed
55 56 57
	%finally generate linked HTML File
    tutFiles(idx).html = publish(tutFiles(idx).name, struct('evalCode', false, 'outputDir', ...
		fullfile(htmlFolder, 'tutorials')));
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
    pos = strfind(tutFiles(idx).html,toolboxFolderName);
    tutFiles(idx).html = tutFiles(idx).html(pos(1)+length(toolboxFolderName)+1:end);
    tutFiles(idx).html = strrep(tutFiles(idx).html,filesep,'/');%conversion for html
    cd(folder)
    
    app = strfind(tutFiles(idx).name,'applications'); %check if application tutorial
    
    %get tutorial comment (for both):
    FileId = fopen(tutFiles(idx).name);
    tutFile = fread(FileId, 'uint8=>char');
    tutFile = tutFile(:)';
    %now search for title/comment for help
    commentStart = strfind(tutFile,'%%');
    if isempty(commentStart)
        commentStart = 0;
    end
    commentEnd   = strfind(tutFile,sprintf('\n'));
    tutFiles(idx).comment = tutFile(commentStart(1)+2 : commentEnd(1)-2);
    fclose(FileId);
    cd(oldfolder);
    
    
    if isempty(app)
        % generate new helptoc.xml
        helpXML = [helpXML,...
            '        <tocitem target="../',...
            tutFiles(idx).html,...
            '" image="$toolbox/matlab/icons/book_mat.gif">',...
            tutFiles(idx).comment,...
            '</tocitem>',...
            sprintf('\n'),...
Marco Berzborn's avatar
Marco Berzborn committed
89
            ]; %#ok<AGROW>
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
        % generate new index_demo.html
        index_demoHTML = [index_demoHTML,...
            '  <tr>',...
            sprintf('\n'),...
            '      <td height="40" width="140" align="left">',...
            sprintf('\n'),...
            '      <a href="../',...
            tutFiles(idx).html,...
            '">',...
            tutFiles(idx).name(1:end-2),...
            '</a>',...
            sprintf('\n'),...
            '      </td>',...
            sprintf('\n'),...
            '      <td height="40" align="left">',...
            sprintf('\n'),...
            '     ',...
            tutFiles(idx).comment,...
            sprintf('\n'),...
            '      </td>',...
            sprintf('\n'),...
            '  </tr>',...
            sprintf('\n'),...
Marco Berzborn's avatar
Marco Berzborn committed
113
            ]; %#ok<AGROW>
114
    else
Marco Berzborn's avatar
Marco Berzborn committed
115
        appDemo{idxApp} = tutFiles(idx); %#ok<AGROW>
116 117 118 119
        idxApp = idxApp+1;
    end
end
% now put all application demos in helptoc.xml + application_demo.html file:
Marco Berzborn's avatar
Marco Berzborn committed
120 121
[app_demoHTML_begin, app_demoHTML_end] = ita_openHTML(fullfile(templateFolder, 'template_application_demos.html'));
app_demoHTML = app_demoHTML_begin;
122 123 124 125 126 127
if ~isempty(appDemo)
    %XML File:
    helpXML = [helpXML,...
        '        <tocitem target="application_demos.html" image="HelpIcon.EXAMPLES">Application Demos',...
        sprintf('\n')];
    for idx = 1:length(appDemo)
Marco Berzborn's avatar
Marco Berzborn committed
128 129
		% no "/applications/" in front of the name 
        appDemo{idx}.name = appDemo{idx}.name(14:end); %#ok<AGROW>
130 131 132 133 134 135 136
        helpXML = [helpXML,...
            '           <tocitem target="../',...
            appDemo{idx}.html,...
            '" image="$toolbox/matlab/icons/book_mat.gif">',...
            appDemo{idx}.comment,...
            '</tocitem>',...
            sprintf('\n'),...
Marco Berzborn's avatar
Marco Berzborn committed
137
            ]; %#ok<AGROW>
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
        
        %HTML File:
        app_demoHTML = [app_demoHTML,...
            '  <tr>',...
            sprintf('\n'),...
            '      <td height="40" width="140" align="left">',...
            sprintf('\n'),...
            '      <a href="../',...
            appDemo{idx}.html,...
            '">',...
            appDemo{idx}.name(1:end-2),...
            '</a>',...
            sprintf('\n'),...
            '      </td>',...
            sprintf('\n'),...
            '      <td height="40" align="left">',...
            sprintf('\n'),...
            '     ',...
            appDemo{idx}.comment,...
            sprintf('\n'),...
            '      </td>',...
            sprintf('\n'),...
            '  </tr>',...
            sprintf('\n'),...
Marco Berzborn's avatar
Marco Berzborn committed
162
            ]; %#ok<AGROW>
163 164 165 166 167 168
    end
    helpXML = [helpXML, '        </tocitem>'];
end
helpXML = [helpXML, helpXML_end]; %put code after insertion point at the end
index_demoHTML = [index_demoHTML, index_demoHTML_end];
app_demoHTML = [app_demoHTML, app_demoHTML_end];
Marco Berzborn's avatar
Marco Berzborn committed
169 170 171 172 173
ita_writeHTML(fullfile(htmlFolder, 'helptoc.xml'),helpXML); %overwrite old file
ita_writeHTML(fullfile(htmlFolder, 'index_demos.html'),index_demoHTML);
ita_writeHTML(fullfile(htmlFolder, 'application_demos.html'),app_demoHTML);
% copy the info xml file as required since MATLAB R2014b
copyfile(fullfile(templateFolder,'template_info.xml'), fullfile(htmlFolder, 'info.xml'));
174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195

%% generate Class/App Documentation in Help Browser
% - Tumbrgel 05/2012
%
% This part should list all Toolbox classes into class.html and
% applications into apps.html
% 1. search for all files with itaBIGLETTER: (those should be classes)
%    sort files from 'application' folder to another array
% 2. edit html Files

%% 1.
idxApp=1;
idxNfile=1;
appName=[];
offset = double('A')-1;
for idx = 1:(double('Z')-offset)
    currentCharFiles = rdir([folder filesep '**' filesep 'ita' char(idx+offset) '*.m']);
    if ~isempty(currentCharFiles)
        for idxY = 1:length(currentCharFiles)
            fileseps = strfind(currentCharFiles(idxY).name,filesep); %search all '\' to get filenameend
            app = strfind(currentCharFiles(idxY).name,'applications'); % sort apps in another list
            if isempty(app)
Marco Berzborn's avatar
Marco Berzborn committed
196
                nFileList{idxNfile} = currentCharFiles(idxY).name((fileseps(end)+1):end); %#ok<AGROW>
197 198
                idxNfile=idxNfile+1;
            else
Marco Berzborn's avatar
Marco Berzborn committed
199
                appFileName{idxApp} = currentCharFiles(idxY).name((fileseps(end)+1):end); %#ok<AGROW>
200 201
                appTempName = currentCharFiles(idxY).name(app+length('applications')+1:end);
                filesepApp = strfind(appTempName,filesep);
Marco Berzborn's avatar
Marco Berzborn committed
202
                appName{idxApp} = appTempName(1:filesepApp(1)-1); %#ok<AGROW>
203 204 205 206 207 208 209 210 211 212 213 214 215
                idxApp=idxApp+1;
            end
        end
    end
end

% now sort all found application files (itaA..., itaB,..., ...., itaZ...) to right application
% store old position to appIdx to read right positions in appFileName
[appName,appIdx] = sort(appName);

%% 2.
% -> edit classes.html
%get template_classes.html content:
Marco Berzborn's avatar
Marco Berzborn committed
216 217
[classesHTML_begin, classesHTML_end] = ita_openHTML(fullfile(templateFolder, 'template_classes.html'));
classesHTML= classesHTML_begin;
218 219 220 221 222 223 224 225
for idx = 1:length(nFileList)
    classesHTML = [classesHTML,...
        '<a href="matlab:doc ',...
        nFileList{idx},...
        '">',...
        nFileList{idx}(1:end-2),...
        '</a><br>',...
        sprintf('\n')
Marco Berzborn's avatar
Marco Berzborn committed
226
        ]; %#ok<AGROW>
227 228 229 230 231 232 233 234 235 236 237 238 239
end
if ~isempty(appName)
    classesHTML = [classesHTML '<br><br>The following classes are app-classes<br>' sprintf('\n')];
    for idx= 1:length(appName)
        if idx>1
            if strcmp(appName(idx),appName(idx-1)) %
                classesHTML = [classesHTML,...
                    '<a href="matlab:doc ',...
                    appFileName{appIdx(idx)},... %appIdx(idx) see comment above (right position)
                    '">',...
                    appFileName{appIdx(idx)}(1:end-2),...
                    '</a><br>',...
                    sprintf('\n')
Marco Berzborn's avatar
Marco Berzborn committed
240
                    ]; %#ok<AGROW>
241 242 243 244 245 246 247 248 249 250 251
            else %next App headline+file
                classesHTML = [classesHTML,...
                    '<br>',...
                    appName{idx},...
                    '<br>',...
                    '<a href="matlab:doc ',...
                    appFileName{appIdx(idx)},...
                    '">',...
                    appFileName{appIdx(idx)}(1:end-2),...
                    '</a><br>',...
                    sprintf('\n')
Marco Berzborn's avatar
Marco Berzborn committed
252
                    ]; %#ok<AGROW>
253 254 255 256 257 258 259 260 261 262 263 264
            end
        else %first App headline+file
            classesHTML = [classesHTML,...
                '<br>',...
                appName{idx},...
                '<br>',...
                '<a href="matlab:doc ',...
                appFileName{appIdx(idx)},...
                '">',...
                appFileName{appIdx(idx)}(1:end-2),...
                '</a><br>',...
                sprintf('\n')
Marco Berzborn's avatar
Marco Berzborn committed
265
                ]; %#ok<AGROW>
266 267 268 269 270
        end
    end
end
classesHTML=[classesHTML, '<br>', sprintf('\n'), classesHTML_end];
%write edited file
Marco Berzborn's avatar
Marco Berzborn committed
271
ita_writeHTML(fullfile(htmlFolder, 'classes.html'), classesHTML);
272 273

%write edited file
Marco Berzborn's avatar
Marco Berzborn committed
274
ita_writeHTML(fullfile(htmlFolder, 'apps.html'), appsHTML);
275 276

%% Generate Kernel Documentation
Marco Berzborn's avatar
Marco Berzborn committed
277 278
[kernelHTML_begin, kernelHTML_end] = ita_openHTML(fullfile(templateFolder, 'template_kernel.html'));
kernelHTML= kernelHTML_begin;
279 280 281 282 283 284 285 286
kernelList = rdir([folder filesep 'kernel' filesep '**' filesep 'KernelDescription.txt']);

kernelHTML = [kernelHTML '<table border="2">' sprintf('\n')];

for idx = 1:numel(kernelList)
    % get Kernelfoldername
    kernelDescriptionPath = kernelList(idx).name;
    pos = strfind(kernelDescriptionPath,'kernel');
Marco Berzborn's avatar
Marco Berzborn committed
287
    kernelName{idx} = kernelDescriptionPath(pos(1)+7:end); %#ok<AGROW>
288
    pos = strfind(kernelName{idx},'KernelDescription.txt');
Marco Berzborn's avatar
Marco Berzborn committed
289
    kernelName{idx} = kernelName{idx}(1:pos(1)-2); %#ok<AGROW>
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
    
    %get m2html documentation fileposition:
    pos = strfind(kernelDescriptionPath,'kernel');
    kernelFolder = kernelDescriptionPath(pos(1):end);
    pos = strfind(kernelFolder,filesep);
    kernelFolder = kernelFolder(1:pos(end));
    kernelDocumentationFile = [folder,...
        filesep,...
        'HTML',...
        filesep,...
        'doc',...
        filesep,...
        toolboxFolderName,...
        filesep,...
        kernelFolder,...
        'index.html'];
    kernelDocumentationFile = strrep(kernelDocumentationFile, filesep, '/'); % replace /,\, for HTML
    %get KernelDescription.txt
    data_ID = fopen(kernelDescriptionPath,'r'); %r read only
    data = fread(data_ID, 'uint8=>char');
    fclose(data_ID);
    data = data(:)'; %get KernelDescription.txt as string
    desPoint = strfind(data,'Description:');
    data = data(desPoint+12:end);
    desPoint = strfind(data,sprintf('\n'));
    data = data(1:desPoint);
    kernelHTML = [kernelHTML,...
        '<tr height="30">', sprintf('\n'),...
        '<td width="100"><a href="file:///', kernelDocumentationFile,'">', kernelName{idx}, '</a></td>', sprintf('\n'),...
        '<td>', data, sprintf('\n'),...
        '</td>',sprintf('\n'),...
Marco Berzborn's avatar
Marco Berzborn committed
321
        '</tr>', sprintf('\n')]; %#ok<AGROW>
322 323
end
kernelHTML = [kernelHTML '</table>' kernelHTML_end];
Marco Berzborn's avatar
Marco Berzborn committed
324
ita_writeHTML(fullfile(htmlFolder, 'kernel.html'), kernelHTML);
325 326

cd(oldfolder);
327
end