How can I generate HTML documentation from help/doc output?

How can I automatically generate reference HTML documentation for my toolbox (mostly classdef classes)? I'm looking for something like what the doc command produces, pulling help text and class properties, methods, etc. from the source files directly, but outputing a set of HTML files I can host on my web-site as a reference manual.

I'm aware of M2HTML (does not handle classdef) and Sphinx+sphinxcontrib.matlab (multiple issues with classdef files), but nothing that handles the MathWorks recommended style of class documentation directly. I've even tried the undocumented help2html, but don't know how to get it to include links.

What does everyone else do? Write your documentation twice? Once in the source files for use with help and doc, and then again, manually reproducing everything for your online reference documentation?

Answer 1

[Yash Sharma]

Hi Ray,

I understand that you want to create HTML documentation for your toolbox that mostly have “classdef” classes.

You can use the publish button that is there on the publish tab in MATLAB or you can use the following code to generate HTML documentation.

% Specify the file or files to include in the documentation
fileToPublish = 'MyClass.m';
% Specify the output format and directory
outputFormat = 'html';
outputDir = 'output/docs';
% Generate the documentation
publish(fileToPublish, 'format', outputFormat, 'outputDir', outputDir);

Please find links to below documentation which I believe will help you for further reference.

• Publish: https://www.mathworks.com/help/matlab/ref/publish.html
• Display Custom Documentation for toolbox: https://www.mathworks.com/help/matlab/matlab_prog/display-custom-documentation.html

[Ray Zimmerman]

I was aware of the publish command, but it does not do what I was asking for (unless I'm missing something).

As I said, "I'm looking for something like what the doc command produces, pulling help text and class properties, methods, etc. from the source files directly, but outputing a set of HTML files".

When I tried publish, the results looked nothing like the output of doc, visually or more importantly in terms of the included content. In particular, the HTML does not include an auto-generated list of properties and methods, let alone the help text for each.

Answer 2

[Ray Zimmerman]

FWIW, since my original post, the matlabdomain for Sphinx has come a long way. At the moment, it is the best option I have encountered.

[Grzegorz Lippe]

Where can I find help for this package?

I tried it, but it only produced an emtpy index.html template.

[Ray Zimmerman]

Unfortunately, there is no single place to find all of the documention for this environment since it consists of multiple pieces. Besides the links above for Sphinx and matlabdomain has, this page can hopefully show you how to get a working build environment for the new MATPOWER documentation. At the time of this posting, you'll need the latest master branch of the matpower repository for this.

Hopefully, this will be a working environment you can use as an example setup for your own MATLAB documentation. If you run into any issues, I'd prefer you follow up by creating a GitHub issue here.

FWIW, changing the matlab_auto_link setting in docs/sphinx/source/conf.py from "all" to "basic" will cause the builds to run much faster when autodocumenting a large library of code, but will not automatically link class/function/method/property names in certain contexts.