ita_generate_helpOverview.m 14.5 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

% -> edit apps.html
Marco Berzborn's avatar
Marco Berzborn committed
274
275
[appsHTML_begin, appsHTML_end] = ita_openHTML(fullfile(templateFolder, 'template_apps.html'));
appsHTML= appsHTML_begin;
276
277
278
279
280
281
282
283
284
285
286
287
288
289
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
%%%%%%%%%%%%%%%%%%%
appfolder = rdir([folder filesep '**' filesep 'ita_apps.m']);
if isempty(appfolder)
    appsHTML = [appsHTML 'sorry you do not have any application installed. Could not find "ita_apps.m"<br>' appsHTML_end];
else
    appfolder = appfolder(1).name;
    temp = strfind(appfolder, filesep);
    appfolder = appfolder(1:temp(end)-1);
    applist = rdir([appfolder filesep '**' filesep 'AppDescription.txt']);
    
    
    appsHTML = [appsHTML '<table border="2">' sprintf('\n')];
    for idx = 1:numel(applist)
        appDescriptionPath = applist(idx).name;
        nameidx = strfind(appDescriptionPath,filesep);
        appDocumentationFile = [appDescriptionPath(1:nameidx(end-2)),...
            'HTML',...
            filesep,...
            'doc',...
            filesep,...
            appDescriptionPath(nameidx(end-3)+1:nameidx(end)),...
            'index.html'];
        appname = appDescriptionPath(nameidx(end-1)+1:nameidx(end)-1);
        appDescriptionPath = strrep(appDescriptionPath, filesep, '/'); %convert ..\.. to ../.. for html
        
        data_ID = fopen(appDescriptionPath,'r'); %r read only
        data = fread(data_ID, 'uint8=>char');
        fclose(data_ID);
        data = data(:)'; %get AppDescription.txt as string
        desPoint = strfind(data,'Description:');
        data = data(desPoint+12:end);
        desPoint = strfind(data,sprintf('\n'));
        data = data(1:desPoint);
        % old: show complete AppDescription.txt....
        %'<td><object data="file:///', appDescriptionPath, '" type="text/plain" width="350" height="90">', sprintf('\n'),...
        %'Ihr Browser kann das Objekt leider nicht anzeigen!</object></td>',sprintf('\n'),..
        appsHTML = [appsHTML,...
            '<tr height="30">', sprintf('\n'),...
            '<td width="100"><a href="file:///', appDocumentationFile,'">', appname, '</a></td>', sprintf('\n'),...
            '<td>', data, sprintf('\n'),...
            '</td>',sprintf('\n'),...
Marco Berzborn's avatar
Marco Berzborn committed
317
            '</tr>', sprintf('\n')]; %#ok<AGROW>
318
319
320
321
322
    end
    appsHTML = [appsHTML '</table>' appsHTML_end];
end

%write edited file
Marco Berzborn's avatar
Marco Berzborn committed
323
ita_writeHTML(fullfile(htmlFolder, 'apps.html'), appsHTML);
324
325

%% Generate Kernel Documentation
Marco Berzborn's avatar
Marco Berzborn committed
326
327
[kernelHTML_begin, kernelHTML_end] = ita_openHTML(fullfile(templateFolder, 'template_kernel.html'));
kernelHTML= kernelHTML_begin;
328
329
330
331
332
333
334
335
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
336
    kernelName{idx} = kernelDescriptionPath(pos(1)+7:end); %#ok<AGROW>
337
    pos = strfind(kernelName{idx},'KernelDescription.txt');
Marco Berzborn's avatar
Marco Berzborn committed
338
    kernelName{idx} = kernelName{idx}(1:pos(1)-2); %#ok<AGROW>
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
    
    %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
370
        '</tr>', sprintf('\n')]; %#ok<AGROW>
371
372
end
kernelHTML = [kernelHTML '</table>' kernelHTML_end];
Marco Berzborn's avatar
Marco Berzborn committed
373
ita_writeHTML(fullfile(htmlFolder, 'kernel.html'), kernelHTML);
374
375

cd(oldfolder);
376
end