23 create a custom buidltool task that can be used out of the box

resources/project/UMvhTnfaEKsbCRaOOLl1x86F4Is/CptS6RPf-mdxP3OCPbhz6pVfFugd.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design"/>
+    </Category>
+</Info>

resources/project/UMvhTnfaEKsbCRaOOLl1x86F4Is/CptS6RPf-mdxP3OCPbhz6pVfFugp.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Info location="mustBeTheme.m" type="File"/>

resources/project/UMvhTnfaEKsbCRaOOLl1x86F4Is/xSrPVEHhWJ_-24ZQrCFK7aG8Q6Ad.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design"/>
+    </Category>
+</Info>

resources/project/UMvhTnfaEKsbCRaOOLl1x86F4Is/xSrPVEHhWJ_-24ZQrCFK7aG8Q6Ap.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Info location="getDefaultFigureSize.m" type="File"/>

resources/project/W7civUV8nZd65rl1QJN6xmVMVQI/yuhCpIfVpbHV0GQ9EbmmIRF4rx8d.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design"/>
+    </Category>
+</Info>

resources/project/W7civUV8nZd65rl1QJN6xmVMVQI/yuhCpIfVpbHV0GQ9EbmmIRF4rx8p.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Info location="DocMakerTask.m" type="File"/>

tbx/docmaker/+docmaker/getDefaultFigureSize.m

@@ -0,0 +1,7 @@
+function s = getDefaultFigureSize()
+%getDefaultFigureSize  Default figure size
+
+p = get( 0, "DefaultFigurePosition" ); % [x y w h]
+s = p(3:4); % [w h]
+
+end % getDefaultFigureSize

tbx/docmaker/+docmaker/mustBeTheme.m

@@ -0,0 +1,10 @@
+function mustBeTheme( theme )
+%mustBeTheme  Validation function for optional named argument Theme
+
+themes = ["none","light","dark","auto"];
+assert( ( ischar( theme ) && ismember( theme, themes ) ) || ...
+    ( isstring( theme ) && isscalar( theme ) && ismember( theme, themes ) ) || ...
+    ( isa( theme, "matlab.graphics.theme.GraphicsTheme" ) && isscalar( theme ) ), ...
+    "Theme must be ""none"", ""light"", ""dark"", ""auto"", or a GraphicsTheme." )
+
+end % mustBeTheme

tbx/docmaker/DocMakerTask.m

@@ -0,0 +1,113 @@
+classdef DocMakerTask < matlab.buildtool.Task
+    %DOCMAKERTASK Generate toolbox documentation using DocMaker.
+    %
+    % See also docconvert, docrun, docindex
+
+    properties
+        % Documentation theme.
+        DocTheme(1, 1) string {mustBeMember( DocTheme, ...
+            ["light", "dark", "auto"] )} = "auto"
+        % Stylesheets to include.
+        Stylesheets(1, :) string {mustBeFile}
+        % Scripts to include.
+        Scripts(1, :) string {mustBeFile}
+        % Root folder for publishing.
+        Root(1, :) string {mustBeFolder, mustBeScalarOrEmpty}
+        % LaTeX interpreter.
+        Interpreter(1, 1) string {mustBeMember( Interpreter, ...
+            ["latex", "none"] )} = "none"
+        % Renderer for LaTeX expressions.
+        MathRenderer(1, 1) string {mustBeMember( MathRenderer, ...
+            ["GitHub", "GitLab", "auto", "none"] )} = "none"
+        % Batching level.
+        Level(1, 1) double {mustBeInteger, ...
+            mustBeInRange( Level, 0, 7 )} = 0
+        % Figure theme.
+        FigureTheme {docmaker.mustBeTheme( FigureTheme )} = "none"
+        % Figure size.
+        FigureSize(1, 2) double {mustBePositive, mustBeReal} = ...
+            docmaker.getDefaultFigureSize()
+    end % properties
+
+    properties ( TaskInput )
+        % Folder containing documentation files in Markdown format.
+        MarkdownFolder(1, :) matlab.buildtool.io.FileCollection
+    end % properties ( TaskInput )
+
+    properties ( TaskOutput, SetAccess = private )
+        % Documentation files, in HTML format.
+        HTMLFiles(1, :) matlab.buildtool.io.FileCollection
+        % Table of contents and doc metadata: helptoc.xml and info.xml.
+        XMLFiles(1, :) matlab.buildtool.io.FileCollection
+        % Documentation resources folder.
+        Resources(1, :) matlab.buildtool.io.FileCollection
+        % Documentation search index.
+        HelpSearchIndex(1, :) matlab.buildtool.io.FileCollection
+    end % properties ( TaskOutput, SetAccess = private )
+
+    methods
+
+        function task = DocMakerTask( markdownFolder, namedArgs )
+            %DOCMAKERTASK Construct the DocMaker build task.
+
+            arguments ( Input )
+                markdownFolder
+                namedArgs.?DocMakerTask
+            end % arguments ( Input )
+
+            % Assign the markdown folder and task outputs.
+            task.MarkdownFolder = markdownFolder;
+            task.HTMLFiles = fullfile( markdownFolder, "**", "*.html" );
+            task.XMLFiles = fullfile( markdownFolder, "*.xml" );
+            task.Resources = fullfile( markdownFolder, "resources" );
+            task.HelpSearchIndex = ...
+                fullfile( markdownFolder, "helpsearch-v*" );
+
+            % Add the task metadata.
+            task.Description = ...
+                "Generate toolbox documentation using DocMaker";
+
+            % Assign any user-specified properties.
+            props = string( fieldnames( namedArgs ).' );
+            for prop = props
+                task.(prop) = namedArgs.(prop);
+            end % for
+
+        end % constructor
+
+    end % methods
+
+    methods ( TaskAction )
+
+        function buildDoc( task, ~ )
+            %BUILDDOC Build the toolbox documentation.
+            %
+            % * Convert Markdown documents to HTML
+            % * Run MATLAB code in HTML documents and insert output
+            % * Create info.xml and helptoc.xml from helptoc.md
+
+            markdownFolder = task.MarkdownFolder.paths();
+            markdownFiles = fullfile( markdownFolder, "**", "*.md" );
+            html = docconvert( markdownFiles, ...
+                "Theme", task.DocTheme, ...
+                "Stylesheets", task.Stylesheets, ...
+                "Scripts", task.Scripts, ...
+                "Root", task.Root, ...
+                "Interpreter", task.Interpreter, ...
+                "MathRenderer", task.MathRenderer );
+            fprintf( 1, "** Converted Markdown doc to HTML\n" )
+
+            docrun( html, ...
+                "Level", task.Level, ...
+                "Theme", task.FigureTheme, ...
+                "FigureSize", task.FigureSize )
+            fprintf( 1, "** Inserted MATLAB output into doc\n" )
+
+            docindex( markdownFolder )
+            fprintf( 1, "** Indexed doc\n" )
+
+        end % buildDoc
+
+    end % methods ( TaskAction )
+
+end % classdef

tbx/docmaker/docrun.m

@@ -39,8 +39,8 @@
 
 arguments
     options.Level (1,1) double {mustBeInteger,mustBeInRange(options.Level,0,7)} = 0
-    options.Theme {mustBeTheme(options.Theme)} = "none"
-    options.FigureSize (1,2) double {mustBePositive,mustBeReal} = getDefaultFigureSize()
+    options.Theme {docmaker.mustBeTheme(options.Theme)} = "none"
+    options.FigureSize (1,2) double {mustBePositive,mustBeReal} = docmaker.getDefaultFigureSize()
 end
 
 % Validate inputs
@@ -404,23 +404,4 @@ function runDiv( div, w, theme )
     "px; height: auto" ); % apply display scaling
 picture.appendChild( img );
 
-end % createResponsiveImage
-
-function mustBeTheme( theme )
-%mustBeTheme  Validation function for optional named argument Theme
-
-themes = ["none","light","dark","auto"];
-assert( ( ischar( theme ) && ismember( theme, themes ) ) || ...
-    ( isstring( theme ) && isscalar( theme ) && ismember( theme, themes ) ) || ...
-    ( isa( theme, "matlab.graphics.theme.GraphicsTheme" ) && isscalar( theme ) ), ...
-    "Theme must be ""none"", ""light"", ""dark"", ""auto"", or a GraphicsTheme." )
-
-end % mustBeTheme
-
-function s = getDefaultFigureSize()
-%getDefaultFigureSize  Default figure size
-
-p = get( 0, "DefaultFigurePosition" ); % [x y w h]
-s = p(3:4); % [w h]
-
-end % getDefaultFigureSize
+end % createResponsiveImage