publish: programmatic reqs

scivision · scivision · commit 8ab64a3d598b · 2025-01-19T23:48:19.000-05:00
diff --git a/+stdlib/cpu_arch.m b/+stdlib/cpu_arch.m
@@ -1,4 +1,5 @@
 %% CPU_ARCH get the CPU architecture
+% requires: java
 
 function arch = cpu_arch()
 
diff --git a/+stdlib/cpu_load.m b/+stdlib/cpu_load.m
@@ -1,4 +1,6 @@
 %% CPU_LOAD get total physical CPU load
+% requires: java
+%
 % Returns the "recent cpu usage" for the whole system.
 %
 % This value is a double in the [0.0,1.0] interval.
diff --git a/+stdlib/create_symlink.m b/+stdlib/create_symlink.m
@@ -1,4 +1,5 @@
 %% CREATE_SYMLINK create symbolic link
+% optional: mex
 %
 %%% Inputs
 % * target: path to link to
diff --git a/+stdlib/disk_available.m b/+stdlib/disk_available.m
@@ -1,4 +1,5 @@
 %% DISK_AVAILABLE disk available space (bytes)
+% requires: java
 %
 % example:  stdlib.disk_available('/')
 %
diff --git a/+stdlib/disk_capacity.m b/+stdlib/disk_capacity.m
@@ -1,4 +1,5 @@
 %% DISK_CAPACITY disk total capacity (bytes)
+% requires: java
 %
 % example:  stdlib.disk_capacity('/')
 
diff --git a/+stdlib/drop_slash.m b/+stdlib/drop_slash.m
@@ -1,4 +1,5 @@
 %% DROP_SLASH drop repeated and trailing slash
+% optional: mex
 %
 % on Windows, if leading double slash, do not drop
 
diff --git a/+stdlib/file_checksum.m b/+stdlib/file_checksum.m
@@ -1,4 +1,6 @@
 %% FILE_CHECKSUM compute hash of file
+% requires: java
+%
 % read in chunks to avoid excessive RAM use
 %
 %%% Inputs
diff --git a/+stdlib/filesystem_type.m b/+stdlib/filesystem_type.m
@@ -1,4 +1,5 @@
 %% FILESYSTEM_TYPE tell type of filesystem
+% requires: java
 %
 % example outputs: ntfs, ext4, apfs, ...
 %
diff --git a/+stdlib/get_modtime.m b/+stdlib/get_modtime.m
@@ -1,4 +1,5 @@
 %% GET_MODTIME get path modification time
+% requires: java
 %
 %%% Inputs
 % * p: path to examine
diff --git a/+stdlib/get_owner.m b/+stdlib/get_owner.m
@@ -1,4 +1,5 @@
 %% GET_OWNER owner of file or directory
+% requires: java
 %
 %%% Inputs
 % * p: path to examine
diff --git a/+stdlib/get_username.m b/+stdlib/get_username.m
@@ -1,5 +1,6 @@
 %% GET_USERNAME tell username of current user
-
+% requires: java
+%
 function n = get_username()
 
 n = javaSystemProperty("user.name");
diff --git a/+stdlib/handle2filename.m b/+stdlib/handle2filename.m
@@ -1,4 +1,5 @@
 %% HANDLE2FILENAME Convert a file handle to a filename
+% requires: java
 
 function n = handle2filename(fileHandle)
 arguments
diff --git a/+stdlib/hard_link_count.m b/+stdlib/hard_link_count.m
@@ -1,4 +1,5 @@
 %% HARD_LINK_COUNT get the number of hard links to a file
+% requires: java
 %
 % Ref:
 % * https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/Files.html#getPosixFileAttributes(java.nio.file.Path,java.nio.file.LinkOption...)
diff --git a/+stdlib/has_java.m b/+stdlib/has_java.m
@@ -1,4 +1,5 @@
 %% HAS_JAVA detect if JVM is available
+% requires: java
 
 function ok = has_java()
 
diff --git a/+stdlib/hostname.m b/+stdlib/hostname.m
@@ -1,5 +1,6 @@
 
 %% HOSTNAME get hostname of local machine
+% requires: java
 %
 % Ref: https://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getHostName--
 
diff --git a/+stdlib/is_admin.m b/+stdlib/is_admin.m
@@ -1,4 +1,5 @@
-%% IS_ADMIN is the process run as root / admin (requires MEX)
+%% IS_ADMIN is the process run as root / admin
+% requires: mex
 
 function is_admin()
 error("buildtool mex")
diff --git a/+stdlib/is_char_device.m b/+stdlib/is_char_device.m
@@ -1,4 +1,6 @@
-%% IS_CHAR_DEVICE is path a character device (Matlab requires MEX)
+%% IS_CHAR_DEVICE is path a character device
+% requires: mex
+%
 % e.g. NUL, /dev/null
 % false if file does not exist
 
diff --git a/+stdlib/is_regular_file.m b/+stdlib/is_regular_file.m
@@ -1,4 +1,5 @@
 %% IS_REGULAR_FILE check if path is a regular file
+% requires: java
 
 function r = is_regular_file(p)
 arguments
diff --git a/+stdlib/is_rosetta.m b/+stdlib/is_rosetta.m
@@ -1,4 +1,6 @@
-%% IS_ROSETTA on Apple Silicon via Rosetta (optional MEX)
+%% IS_ROSETTA on Apple Silicon via Rosetta
+% optional: mex
+%
 % true if Matlab on Apple Silicon CPU is built for Intel x86_64
 
 function r = is_rosetta()
diff --git a/+stdlib/is_symlink.m b/+stdlib/is_symlink.m
@@ -1,4 +1,5 @@
-%% IS_SYMLINK is path a symbolic link (optional MEX)
+%% IS_SYMLINK is path a symbolic link
+% optional: mex
 
 function ok = is_symlink(p)
 arguments
diff --git a/+stdlib/is_wsl.m b/+stdlib/is_wsl.m
@@ -1,4 +1,6 @@
-%% IS_WSL detect if running under WSL (optional MEX)
+%% IS_WSL detect if running under WSL
+% optional: mex
+%
 % Detects if Matlab or GNU Octave is installed and running from within
 % Windows Subsystem for Linux
 
diff --git a/+stdlib/java_api.m b/+stdlib/java_api.m
@@ -1,4 +1,5 @@
 %% JAVA_API Java API version
+% requires: java
 
 function api = java_api()
 
diff --git a/+stdlib/java_vendor.m b/+stdlib/java_vendor.m
@@ -1,4 +1,5 @@
 %% JAVA_VENDOR get vendor of Java Virtual Machine
+% requires: java
 
 function v = java_vendor()
 
diff --git a/+stdlib/java_version.m b/+stdlib/java_version.m
@@ -1,4 +1,6 @@
 %% JAVA_VERSION get version of Java Virtual Machine
+% requires: java
+%
 % this gives a long string with more detail
 % version("-java")
 
diff --git a/+stdlib/md5sum.m b/+stdlib/md5sum.m
@@ -1,5 +1,5 @@
 %% MD5SUM compute MD5 hash of file
-
+% requires: java
 function hash = md5sum(file)
 arguments
   file (1,1) string
diff --git a/+stdlib/os_version.m b/+stdlib/os_version.m
@@ -1,4 +1,5 @@
 %% OS_VERSION Get operating system name and version.
+% requires: java
 %
 % Note: for Windows 11, need new-enough Java version to show Windows 11
 % instead of Windows 10.
diff --git a/+stdlib/proximate_to.m b/+stdlib/proximate_to.m
@@ -1,5 +1,6 @@
-%% PROXIMATE_TO relative path to base (requires MEX)
-%
+%% PROXIMATE_TO relative path to base
+% requires: mex
+
 %%% Inputs
 % * base (1,1) string
 % * other (1,1) string
diff --git a/+stdlib/ram_free.m b/+stdlib/ram_free.m
@@ -1,4 +1,6 @@
 %% RAM_FREE get free physical RAM
+% requires: java
+%
 % get free physical RAM across operating systems
 % https://docs.oracle.com/en/java/javase/21/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getFreeMemorySize()
 %
diff --git a/+stdlib/ram_total.m b/+stdlib/ram_total.m
@@ -1,4 +1,6 @@
 %% RAM_TOTAL get total physical RAM
+% requires: java
+%
 % get total physical RAM across operating systems
 % https://docs.oracle.com/en/java/javase/21/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getTotalPhysicalMemorySize()
 %
diff --git a/+stdlib/relative_to.m b/+stdlib/relative_to.m
@@ -1,4 +1,5 @@
-%% RELATIVE_TO relative path to base (requires MEX)
+%% RELATIVE_TO relative path to base
+% requires: mex
 %
 %%% Inputs
 % * base (1,1) string
diff --git a/+stdlib/set_modtime.m b/+stdlib/set_modtime.m
@@ -1,4 +1,5 @@
 %% SET_MODTIME set modification time of path
+% requires: java
 
 function ok = set_modtime(p, t)
 arguments
diff --git a/+stdlib/set_permissions.m b/+stdlib/set_permissions.m
@@ -1,4 +1,5 @@
-%% SET_PERMISSIONS set path permissions (Matlab requires MEX)
+%% SET_PERMISSIONS set path permissions
+% requires: mex
 %
 %%% Inputs
 % * path (1,1) string
diff --git a/+stdlib/sha256sum.m b/+stdlib/sha256sum.m
@@ -1,4 +1,5 @@
 %% SHA256SUM compute sha256 hash of file
+% requires: java
 
 function hash = sha256sum(file)
 arguments
diff --git a/+stdlib/subprocess_run.m b/+stdlib/subprocess_run.m
@@ -1,4 +1,6 @@
 %% SUBPROCESS_RUN run process for Matlab only
+% requires: java
+%
 % with optional cwd, env. vars, stdin, timeout
 %
 % handles command lines with spaces
diff --git a/+stdlib/subprocess_run_octave.m b/+stdlib/subprocess_run_octave.m
@@ -1,4 +1,6 @@
 %% SUBPROCESS_RUN_OCTAVE run process for GNU Octave only
+% requires: java
+%
 % with optional cwd, env. vars, stdin, timeout
 %
 % handles command lines with spaces
diff --git a/+stdlib/windows_shortname.m b/+stdlib/windows_shortname.m
@@ -1,4 +1,6 @@
-%% WINDOWS_SHORTNAME Retrieves the Windows short name (optional MEX)
+%% WINDOWS_SHORTNAME Retrieves the Windows short name
+% optional: mex
+%
 % (8.3 character) filename
 %
 %  Example of using a COM server (Scripting.FileSystemObject) in Windows
diff --git a/buildfile.m b/buildfile.m
@@ -106,7 +106,6 @@ function publishTask(context)
 ["src/drop_slash.cpp", normal], ...
 };
 
-%%  new in R2024b
 if isMATLABReleaseOlderThan("R2024b")
 srcs{end+1} = ["src/is_symlink.cpp", win, sym];
 srcs{end+1} = ["src/create_symlink.cpp", win, sym];
diff --git a/private/publish_gen_index_html.m b/private/publish_gen_index_html.m
@@ -7,6 +7,9 @@
 % * https://www.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html
 %
 % for package code -- assumes no classes and depth == 1
+%
+% if *.mex* files are present, publish fails
+
 function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
 arguments
   pkg_name (1,1) string
@@ -30,12 +33,22 @@ function publish_gen_index_html(pkg_name, tagline, project_url, 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>", ...
-     "<p>Project URL: <a href=" + project_url + ">" + project_url + "</a></p>", ...
-     "<h2>API Reference</h2>"];
+mr = matlabRelease();
+
+
+txt = ["<!DOCTYPE html>", ...
+"<head>",...
+'<meta name="color-scheme" content="dark light">', ...
+'<meta name="viewport" content="width=device-width, initial-scale=1">', ...
+'<meta generator="Matlab ' + mr.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"));
 
@@ -48,8 +61,8 @@ function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
 disp(doc_fn)
 
 % inject summary for each function into Readme.md
-summary = split(string(help(pkg_name + "." + name)), newline);
-words = split(strip(summary(1)), " ");
+help_txt = split(string(help(pkg_name + "." + name)), newline);
+words = split(strip(help_txt(1)), " ");
 
 % error if no docstring
 fname = words(1);
@@ -60,7 +73,13 @@ function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
   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
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% CPU_ARCH get the CPU architecture`
	`2`	`+% requires: java`
`2`	`3`
`3`	`4`	`function arch = cpu_arch()`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,6 @@`
`1`	`1`	`%% CPU_LOAD get total physical CPU load`
	`2`	`+% requires: java`
	`3`	`+%`
`2`	`4`	`% Returns the "recent cpu usage" for the whole system.`
`3`	`5`	`%`
`4`	`6`	`% This value is a double in the [0.0,1.0] interval.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% CREATE_SYMLINK create symbolic link`
	`2`	`+% optional: mex`
`2`	`3`	`%`
`3`	`4`	`%%% Inputs`
`4`	`5`	`% * target: path to link to`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% DISK_AVAILABLE disk available space (bytes)`
	`2`	`+% requires: java`
`2`	`3`	`%`
`3`	`4`	`% example: stdlib.disk_available('/')`
`4`	`5`	`%`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% DISK_CAPACITY disk total capacity (bytes)`
	`2`	`+% requires: java`
`2`	`3`	`%`
`3`	`4`	`% example: stdlib.disk_capacity('/')`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% DROP_SLASH drop repeated and trailing slash`
	`2`	`+% optional: mex`
`2`	`3`	`%`
`3`	`4`	`% on Windows, if leading double slash, do not drop`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,6 @@`
`1`	`1`	`%% FILE_CHECKSUM compute hash of file`
	`2`	`+% requires: java`
	`3`	`+%`
`2`	`4`	`% read in chunks to avoid excessive RAM use`
`3`	`5`	`%`
`4`	`6`	`%%% Inputs`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% FILESYSTEM_TYPE tell type of filesystem`
	`2`	`+% requires: java`
`2`	`3`	`%`
`3`	`4`	`% example outputs: ntfs, ext4, apfs, ...`
`4`	`5`	`%`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% GET_MODTIME get path modification time`
	`2`	`+% requires: java`
`2`	`3`	`%`
`3`	`4`	`%%% Inputs`
`4`	`5`	`% * p: path to examine`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`%% GET_OWNER owner of file or directory`
	`2`	`+% requires: java`
`2`	`3`	`%`
`3`	`4`	`%%% Inputs`
`4`	`5`	`% * p: path to examine`