Skip to content

Commit 4c443a2

Browse files
scivisionscivision
committed
publish: use Matlab R2026a+ metafunctions
This is clearer and more robust than the previous method
1 parent 23f0b36 commit 4c443a2

File tree

5 files changed

+26
-39
lines changed

5 files changed

+26
-39
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ jobs:
3232

3333
strategy:
3434
matrix:
35-
release: ["latest"]
35+
release: ["latest-including-prereleases"]
36+
# FIXME: temporary until R2026a is released
3637

3738
environment:
3839
name: github-pages

‎private/index_html.m‎ renamed to ‎archive/index_html.m‎

File renamed without changes.

‎private/publish_gen_index_html.m‎ renamed to ‎archive/publish_gen_index_html.m‎

File renamed without changes.

‎private/style.css‎ renamed to ‎archive/style.css‎

File renamed without changes.

‎buildfile.m‎

Lines changed: 24 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -108,77 +108,63 @@
108108

109109
function publishTask(context)
110110
% publish HTML inline documentation strings to individual HTML files
111+
% requires Matlab >= R2026a
111112
%
112113
% References:
113114
% https://www.mathworks.com/help/matlab/matlab_prog/display-custom-documentation.html
114115
% https://www.mathworks.com/help/matlab/matlab_prog/create-a-help-summary-contents-m.html
115-
pkg_name = '+stdlib';
116-
pkg_root = fullfile(context.Plan.RootFolder, pkg_name);
116+
pkg_dir = '+stdlib';
117+
pkg_name = extractAfter(pkg_dir, '+');
118+
pkg_root = fullfile(context.Plan.RootFolder, pkg_dir);
117119
html_dir = fullfile(pkg_root, 'html');
118120
contents = fullfile(pkg_root, 'Contents.m');
119121

120-
% styleFile = fullfile(context.Plan.RootFolder, "private/style.css");
121-
%
122-
% readme = publish_gen_index_html("stdlib", ...
123-
% "A standard library of functions for Matlab.", ...
124-
% "https://github.com/geospace-code/matlab-stdlib", ...
125-
% html_dir, styleFile);
126-
127-
pkg = what(pkg_root);
128-
funcs = string(pkg.m).';
129-
pn = extractAfter(pkg_name, 1);
122+
if ~isfolder(html_dir)
123+
mkdir(html_dir);
124+
end
130125

126+
%% HTML front matter
131127
txt = ["%% Standard library of functions for MATLAB", "%"];
132128

133-
repo = gitrepo(pkg.path);
129+
repo = gitrepo(pkg_root);
134130
txt(end+1) = "% Git branch / commit: " + repo.CurrentBranch.Name + " " + ...
135131
repo.LastCommit.ID{1}(1:8) + " " + string(repo.LastCommit.CommitterDate);
136132

137-
138133
txt = [txt, "%", "% <https://github.com/geospace-code/matlab-stdlib GitHub Source Code>", "%", ...
139134
"% Library Functions:", "%", ...
140135
"% <html>", "% <table>", "% <tr><th>Function</th> <th>Description</th> <th>Backends</th></tr>"];
141136

142137
writelines(join(txt, newline), contents, WriteMode="overwrite")
143138

144-
139+
%% iterate over namespace functions
145140
Nbe = struct(dotnet=0, java=0, perl=0, python=0, sys=0, native=0, legacy=0, top_level=0);
146141

142+
funcs = namespaceFunctions(pkg_name).';
143+
backends = innerNamespaces(pkg_name).';
144+
147145
for m = funcs
148146
Nbe.top_level = Nbe.top_level + 1;
149147

150-
if m == "Contents.m"
151-
continue
152-
end
153-
154-
[~, name] = fileparts(m);
155-
156-
doc_fn = publish(pn + "." + name, evalCode=false, outputDir=html_dir);
148+
doc_fn = publish(m.NamespaceName + "." + m.Name, evalCode=false, outputDir=html_dir);
157149
disp(doc_fn)
158150

159151
% inject summary for each function
160-
help_txt = splitlines(string(help(pn + "." + name)));
161-
words = split(strip(help_txt(1)), " ");
152+
assert(~isempty(m.Description))
162153

163-
% error if no docstring
164-
fname = words(1);
165-
assert(endsWith(fname, name, IgnoreCase=true), "fname %s does not match name %s \nis there a docstring at the top of the .m file?", fname, name)
166-
167-
line = "% <tr><td><a href=" + name + ".html>" + fname + "</a></td><td>";
168-
if numel(words) > 1
169-
line = join([line, words(2:end).']);
170-
end
154+
line = "% <tr><td><a href=" + m.Name + ".html>" + m.Name + "</a></td><td>";
155+
line = join([line, m.Description]);
171156

172157
req = "";
173-
for bkd = string(pkg.packages).'
174-
subfun = pn + "." + bkd + "." + name;
158+
for b = backends
159+
subfun = b + "." + m.Name;
160+
bn = extractAfter(b, '.');
175161
if ~isempty(which(subfun))
176-
Nbe.(bkd) = Nbe.(bkd) + 1;
162+
Nbe.(bn) = Nbe.(bn) + 1;
177163

178-
doc_fn = publish(subfun, evalCode=false, outputDir=html_dir + "/" + bkd);
164+
doc_fn = publish(subfun, evalCode=false, outputDir=html_dir + "/" + bn);
179165
disp(doc_fn)
180166

181-
req = req + " <a href=" + bkd + "/" + name + ".html>" + bkd + "</a>";
167+
req = req + " <a href=" + bn + "/" + m.Name + ".html>" + bn + "</a>";
182168
end
183169
end
184170

@@ -197,7 +183,7 @@ function publishTask(context)
197183

198184
writelines(join(line, newline), contents, WriteMode="append")
199185

200-
readme = publish(pn + ".Contents", evalCode=false, showCode=false);
186+
readme = publish(pkg_name + ".Contents", evalCode=false, showCode=false);
201187

202188
movefile(readme, html_dir + "/index.html");
203189
readme = html_dir + "/index.html";

0 commit comments

Comments
 (0)