publish subfunctions too

scivision · scivision · commit 0ae0a67dd724 · 2025-07-28T18:06:05.000-04:00
diff --git a/+stdlib/+dotnet/cpu_arch.m b/+stdlib/+dotnet/cpu_arch.m
@@ -1,3 +1,5 @@
+%% DOTNET.CPU_ARCH get the Operating System architecture
+
 function a = cpu_arch()
 a = string(System.Runtime.InteropServices.RuntimeInformation.OSArchitecture);
 % https://learn.microsoft.com/en-us/dotnet/core/compatibility/interop/7.0/osarchitecture-emulation
diff --git a/+stdlib/+dotnet/create_symlink.m b/+stdlib/+dotnet/create_symlink.m
@@ -1,3 +1,5 @@
+%% DOTNET.CREATE_SYMLINK create symbolic link to target
+
 function ok = create_symlink(target, link)
 
 ok = false;
diff --git a/+stdlib/+dotnet/device.m b/+stdlib/+dotnet/device.m
@@ -1,3 +1,5 @@
+%% DOTNET.DEVICE find the drive device ID
+
 function i = device(path)
 
 % this has been not so stable, so we disabled it and leave it here for reference.
diff --git a/+stdlib/+dotnet/disk_available.m b/+stdlib/+dotnet/disk_available.m
@@ -1,3 +1,5 @@
+%% DOTNET.DISK_AVAILABLE find the disk space available to the user
+
 function f = disk_available(p)
 
 f = uint64(0);
diff --git a/+stdlib/+dotnet/disk_capacity.m b/+stdlib/+dotnet/disk_capacity.m
@@ -1,3 +1,5 @@
+%% DOTNET.DISK_CAPACITY find the overall disk capacity visible to user
+
 function f = disk_capacity(d)
 
 f = uint64(0);
diff --git a/+stdlib/+dotnet/filesystem_type.m b/+stdlib/+dotnet/filesystem_type.m
@@ -1,3 +1,5 @@
+%% DOTNET.FILESYSTEM_TYPE type of the partition e.g. NTFS, ext4, ...
+
 function t = filesystem_type(p)
 
 if ~stdlib.exists(p)
diff --git a/+stdlib/+dotnet/get_hostname.m b/+stdlib/+dotnet/get_hostname.m
@@ -1,3 +1,6 @@
+%% DOTNET.GET_HOSTNAME get the computer network hostname
+% not necessary FQDN
+
 function n = get_hostname()
 
 n = string(System.Environment.MachineName);
diff --git a/+stdlib/+dotnet/get_owner.m b/+stdlib/+dotnet/get_owner.m
@@ -1,3 +1,5 @@
+%% DOTNET.GET_OWNER get the owner of a filepath
+
 function o = get_owner(p)
 
 if ~stdlib.exists(p)
diff --git a/+stdlib/+dotnet/get_username.m b/+stdlib/+dotnet/get_username.m
@@ -1,3 +1,5 @@
+%% DOTNET.GET_USERNAME get the login name
+
 function n = get_username()
 % https://learn.microsoft.com/en-us/dotnet/api/system.environment.username
 
diff --git a/+stdlib/+dotnet/is_admin.m b/+stdlib/+dotnet/is_admin.m
@@ -1,3 +1,5 @@
+%% DOTNET.IS_ADMIN is the user running as root?
+
 function y = is_admin()
 
 % com.sun.security.auth.module.NTSystem().getGroupIDs();
diff --git a/+stdlib/+dotnet/is_symlink.m b/+stdlib/+dotnet/is_symlink.m
@@ -1,3 +1,5 @@
+%% DOTNET.IS_SYMLINK check if a file is a symbolic link
+
 function y = is_symlink(p)
 
 try
diff --git a/+stdlib/+dotnet/ram_total.m b/+stdlib/+dotnet/ram_total.m
@@ -1,3 +1,5 @@
+%% DOTNET.RAM_TOTAL get total physical RAM
+
 function bytes = ram_total()
   % .NET is 2-3x faster than Java for this
   % https://learn.microsoft.com/en-us/dotnet/api/system.gcmemoryinfo.totalavailablememorybytes
diff --git a/+stdlib/+dotnet/read_symlink.m b/+stdlib/+dotnet/read_symlink.m
@@ -1,3 +1,5 @@
+%% DOTNET.READ_SYMLINK resolve the symbolic links of a filepath
+
 function r = read_symlink(p)
 
 try
diff --git a/+stdlib/+dotnet/relative_to.m b/+stdlib/+dotnet/relative_to.m
@@ -1,3 +1,5 @@
+%% DOTNET.RELATIVE_TO find the relative path to other from base
+
 function rel = relative_to(base, other)
 
 if stdlib.strempty(other)
diff --git a/+stdlib/+java/is_writable.m b/+stdlib/+java/is_writable.m
@@ -1,3 +1,5 @@
+%% JAVA.IS_WRITABLE is a filepath writable
+
 function y = is_writable(p)
 
 % https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/nio/file/Files.html#isWritable(java.nio.file.Path)
diff --git a/+stdlib/+java/ram_total.m b/+stdlib/+java/ram_total.m
@@ -1,3 +1,5 @@
+%% JAVA.RAM_TOTAL get the total physical RAM
+
 function bytes = ram_total()
 
 % https://docs.oracle.com/en/java/javase/21/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getTotalMemorySize()
diff --git a/+stdlib/+java/read_symlink.m b/+stdlib/+java/read_symlink.m
@@ -1,3 +1,6 @@
+%% JAVA.READ_SYMLINK resolve the symbolic links of a filepath
+% empty if no symlinks
+
 function r = read_symlink(p)
 
 if stdlib.is_symlink(p)
diff --git a/+stdlib/+java/set_modtime.m b/+stdlib/+java/set_modtime.m
@@ -1,3 +1,5 @@
+%% JAVA.SET_MODTIME set the modification time of a filepath
+
 function ok = set_modtime(p, utc)
 
 if isdatetime(utc)
diff --git a/+stdlib/+python/has_psutil.m b/+stdlib/+python/has_psutil.m
@@ -1,6 +1,8 @@
+%% PYTHON.HAS_PSUTIL is Python psutil module availble
+
 function y = has_psutil()
-% this is to avoid Matlab < R2022a JIT but with Python in general
 
 y = pvt_psutil();
+% this is to avoid Matlab < R2022a JIT but with Python in general
 
 end
diff --git a/+stdlib/+python/version.m b/+stdlib/+python/version.m
@@ -1,3 +1,5 @@
+%% PYTHON.VERSION major.minor version of the Python executable being used
+
 function v = version(force_old)
 arguments
   force_old (1,1) logical = false
diff --git a/private/publish_gen_index_html.m b/private/publish_gen_index_html.m
@@ -47,12 +47,44 @@ function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
 "<p>Project URL: <a href=" + project_url + ">" + project_url + "</a></p>", ...
 "<h2>API Reference</h2>"];
 fid = fopen(readme, 'w');
-fprintf(fid, join(txt, "\n"));
+fprintf(fid, join(txt, newline));
 
-for sub = pkg.m.'
+publish_pkg(fid, pkg, pkg_name)
 
-s = sub{1};
-[~, name] = fileparts(s);
+fprintf(fid, "The functions below are for diagnostics or internal use. Users will only use the functions above.")
+
+for i = 1:numel(pkg.packages)
+  sn = pkg.packages(i);
+  sn = sn{1};
+  spkg = what(fullfile("+" + pkg_name, sn));
+  
+  publish_pkg(fid, spkg, pkg_name)
+end
+
+fprintf(fid, "</body> </html>");
+
+fclose(fid);
+
+end
+
+
+function publish_pkg(fid, pkg, pkg_name)
+
+outdir = fileparts(fopen(fid));
+
+[~, subname] = fileparts(pkg.path);
+if ~endsWith(subname, pkg_name)
+  pkg_name = pkg_name + "." + subname(2:end);
+  relpath = subname(2:end);
+  outdir = fullfile(outdir, relpath);
+  fprintf(fid, strcat('<h3>', pkg_name, '</h3>', newline));
+else
+  relpath = '';
+end
+
+for fun = pkg.m.'
+
+[~, name] = fileparts(fun{1});
 
 doc_fn = publish(pkg_name + "." + name, evalCode=false, outputDir=outdir);
 disp(doc_fn)
@@ -63,11 +95,11 @@ function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
 
 % error if no docstring
 fname = words(1);
-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)
+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)
 
-line = "<a href=" + name + ".html>" + fname + "</a> ";
+line = "<a href=" + relpath + "/" + name + ".html>" + fname + "</a> ";
 if(length(words) > 1)
-  line = line + join(words(2:end));
+   line = join([line, words(2:end).']);
 end
 
 req = "";
@@ -76,12 +108,8 @@ function publish_gen_index_html(pkg_name, tagline, project_url, outdir)
   req = "<strong>(" + strip(help_txt(2), " ") + ")</strong>";
 end
 
-fprintf(fid, line + " " + req + "<br>\n");
+fprintf(fid, line + " " + req + "<br>" + newline);
 
 end
 
-fprintf(fid, "</body> </html>");
-
-fclose(fid);
-
 end

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.CPU_ARCH get the Operating System architecture`
	`2`	`+`
`1`	`3`	`function a = cpu_arch()`
`2`	`4`	`a = string(System.Runtime.InteropServices.RuntimeInformation.OSArchitecture);`
`3`	`5`	`% https://learn.microsoft.com/en-us/dotnet/core/compatibility/interop/7.0/osarchitecture-emulation`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.CREATE_SYMLINK create symbolic link to target`
	`2`	`+`
`1`	`3`	`function ok = create_symlink(target, link)`
`2`	`4`
`3`	`5`	`ok = false;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.DEVICE find the drive device ID`
	`2`	`+`
`1`	`3`	`function i = device(path)`
`2`	`4`
`3`	`5`	`% this has been not so stable, so we disabled it and leave it here for reference.`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.DISK_AVAILABLE find the disk space available to the user`
	`2`	`+`
`1`	`3`	`function f = disk_available(p)`
`2`	`4`
`3`	`5`	`f = uint64(0);`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.DISK_CAPACITY find the overall disk capacity visible to user`
	`2`	`+`
`1`	`3`	`function f = disk_capacity(d)`
`2`	`4`
`3`	`5`	`f = uint64(0);`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.FILESYSTEM_TYPE type of the partition e.g. NTFS, ext4, ...`
	`2`	`+`
`1`	`3`	`function t = filesystem_type(p)`
`2`	`4`
`3`	`5`	`if ~stdlib.exists(p)`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.GET_OWNER get the owner of a filepath`
	`2`	`+`
`1`	`3`	`function o = get_owner(p)`
`2`	`4`
`3`	`5`	`if ~stdlib.exists(p)`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.GET_USERNAME get the login name`
	`2`	`+`
`1`	`3`	`function n = get_username()`
`2`	`4`	`% https://learn.microsoft.com/en-us/dotnet/api/system.environment.username`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+%% DOTNET.IS_ADMIN is the user running as root?`
	`2`	`+`
`1`	`3`	`function y = is_admin()`
`2`	`4`
`3`	`5`	`% com.sun.security.auth.module.NTSystem().getGroupIDs();`