latest buildfile and publish

geospace-code · Jan 22, 2025 · a910511 · a910511
1 parent 15c7813
commit a910511
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 68 deletions.
diff --git a/.github/workflows/composite-buildtool/action.yml b/.github/workflows/composite-buildtool/action.yml
@@ -7,15 +7,15 @@ runs:
   steps:
 
   - name: Run Matlab buildtool
-    if: ${{ matrix.release >= 'R2022b' || matrix.release == 'latest' || matrix.release == 'latest-including-prerelease' }}
+    if: ${{ matrix.release >= 'R2022b' || startsWith(matrix.release, 'latest') }}
     uses: matlab-actions/run-build@v2
     with:
       startup-options: ${{ matrix.startup-options }}
-      tasks: test
+      tasks: check test
 
 
   - name: Run tests (manual)
-    if: ${{ matrix.release < 'R2022b' && matrix.release != 'latest' && matrix.release != 'latest-including-prerelease' }}
+    if: ${{ matrix.release < 'R2022b' && !startsWith(matrix.release, 'latest') }}
     uses: matlab-actions/run-tests@v2
     with:
       select-by-folder: test
diff --git a/.gitignore b/.gitignore
@@ -2,5 +2,5 @@ docs/
 resources/
 *.asv
 *.m~
-code-coverage/
-test-results/
+code-coverage.xml
+.buildtool/
diff --git a/buildfile.m b/buildfile.m
@@ -1,33 +1,42 @@
 function plan = buildfile
-plan = buildplan(localfunctions);
+
+plan = buildplan();
+
 plan.DefaultTasks = "test";
-plan("test").Dependencies = "check";
+
+pkg_name = "+matmap3d";
+
+if isMATLABReleaseOlderThan("R2023b")
+  plan("test") = matlab.buildtool.Task(Actions=@legacyTestTask);
+else
+  plan("check") = matlab.buildtool.tasks.CodeIssuesTask(pkg_name, IncludeSubfolders=true);
+  plan("test") = matlab.buildtool.tasks.TestTask("test", Strict=false);
 end
 
-function checkTask(~)
-% Identify code issues (recursively all Matlab .m files)
-issues = codeIssues;
-assert(isempty(issues.Issues), formattedDisplayText(issues.Issues))
+if ~isMATLABReleaseOlderThan("R2024a")
+  plan("coverage") = matlab.buildtool.tasks.TestTask(Description="code coverage", SourceFiles="test", Strict=false, CodeCoverageResults="code-coverage.xml");
 end
 
-function testTask(~)
-  r = runtests(IncludeSubfolders=true, strict=true, UseParallel=true);
+plan("publish") = matlab.buildtool.Task(Description="HTML inline doc generate", Actions=@publishTask);
+
 
-  assert(~isempty(r), "No tests were run")
-  assertSuccess(r)
 end
 
-function coverageTask(~)
-  cwd = fileparts(mfilename('fullpath'));
 
-  coverage_run("matmap3d", fullfile(cwd, "test"))
+function legacyTestTask(context)
+r = runtests(fullfile(context.Plan.RootFolder, "test"), Strict=false);
+% Parallel Computing Toolbox takes more time to startup than is worth it for this task
+
+assert(~isempty(r), "No tests were run")
+assertSuccess(r)
 end
 
-function publishTask(~)
-  cwd = fileparts(mfilename('fullpath'));
-  outdir = fullfile(cwd, "docs");
+
+function publishTask(context)
+  outdir = fullfile(context.Plan.RootFolder, "docs");
 
   publish_gen_index_html("matmap3d", ...
-    "Geographic Map coordinate transform functions for Matlab", ...
+    "Geographic coordinate tranformation functions for Matlab.", ...
+    "https://github.com/geospace-code/matmap3d", ...
     outdir)
 end
diff --git a/private/coverage_run.m b/private/coverage_run.m
diff --git a/private/publish_gen_index_html.m b/private/publish_gen_index_html.m
@@ -7,7 +7,16 @@
 % * https://www.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html
 %
 % for package code -- assumes no classes and depth == 1
-function publish_gen_index_html(pkg_name, tagline, outdir)
+%
+% if *.mex* files are present, publish fails
+
+function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
+arguments
+  pkg_name (1,1) string
+  tagline (1,1) string
+  project_url (1,1) string
+  outdir (1,1) string
+end
 
 pkg = what("+" + pkg_name);
 % "+" avoids picking up cwd of same name
@@ -24,37 +33,50 @@ function publish_gen_index_html(pkg_name, tagline, outdir)
   mkdir(outdir);
 end
 
-txt = ["<!DOCTYPE html> <head> <title>" + pkg_name + " API</title> <body>", ...
-     "<h1>" + pkg_name + " API</h1>", ...
-     "<p>" + tagline + "</p>", ...
-     "<p>" + git_txt + "</p>", ...
-     "<h2>API Reference</h2>"];
+txt = ["<!DOCTYPE html>", ...
+"<head>",...
+'<meta name="color-scheme" content="dark light">', ...
+'<meta name="viewport" content="width=device-width, initial-scale=1">', ...
+'<meta name="generator" content="Matlab ' + matlabRelease().Release + '">', ...
+"<title>" + pkg_name + " API</title>", ...
+"</head>", ...
+"<body>", ...
+"<h1>" + pkg_name + " API</h1>", ...
+"<p>" + tagline + "</p>", ...
+"<p>" + git_txt + "</p>", ...
+"<p>Project URL: <a href=" + project_url + ">" + project_url + "</a></p>", ...
+"<h2>API Reference</h2>"];
 fid = fopen(readme, 'w');
 fprintf(fid, join(txt, "\n"));
 
 for sub = pkg.m.'
 
 s = sub{1};
 [~, name] = fileparts(s);
+
 doc_fn = publish(pkg_name + "." + name, evalCode=false, outputDir=outdir);
 disp(doc_fn)
 
-% inject summary into Readme.md
-summary = split(string(help(pkg_name + "." + name)), newline);
-words = split(strip(summary(1)), " ");
+% inject summary for each function into Readme.md
+help_txt = split(string(help(pkg_name + "." + name)), newline);
+words = split(strip(help_txt(1)), " ");
 
-% purposefully this will error if no docstring
+% error if no docstring
 fname = words(1);
-if(lower(fname) ~= lower(name))
-  error("fname %s does not match name %s", fname, name)
-end
+assert(lower(fname) == lower(name), "fname %s does not match name %s \nis there a docstring at the top of the .m file?", fname, name)
 
 line = "<a href=" + name + ".html>" + fname + "</a> ";
 if(length(words) > 1)
   line = line + join(words(2:end));
 end
 
-fprintf(fid, line + "<br>\n");
+req = "";
+
+if contains(help_txt(2), "requires:") || contains(help_txt(2), "optional:")
+  req = "<strong>(" + strip(help_txt(2), " ") + ")</strong>";
+end
+
+fprintf(fid, line + " " + req + "<br>\n");
 
 end