What is the Mathworks way to generate Matlab HTML documentation?
Solution 1
I think you've researched this topic well (how to generate HTML documentation from MATLAB functions), now it's up to you to choose which method works best for you.
The publish
function could be used to author documentation. You write regular M-files with specially crafted comments (in fact the file could be all comments with no code), then you publish the file to obtain rendered HTML (it also supports other targets such as PDF, DOC, LaTeX, etc...). Think of it as a simpler MATLAB-specific version of Markdown which used here on Stack Exchange sites to format posts.
One aspect you didn't mention is integrating the generated documentation into the builtin Help viewer. This is done by creating info.xml
and demos.xml
files, and organizing the documentation in a specific way. You could also make your custom docs searchable by building Lucene index files using builddocsearchdb
function (which internally powers the search functionality in MATLAB custom docs). Note that it doesn't matter how you generated the HTML docs (you could have used publish
or even manually written HTML files).
In fact the publish
-based workflow is extendable, and you could use it in interesting ways by creating custom XSL template files to transform and render the parsed comments. For example I've seen it used to render equations using MathJax instead of relying on the built-in solution. Another example is publishing to MediaWiki markup (format used by Wikipedia). Other people use it to write blog posts (see the official blogs on the MATLAB Central which are creating this way), or even generate text files later processed by static site generators (like Jekyll and Octopress frameworks).
As far as I know, there are no public tools available that inspect MATLAB code on a deeper level and analyze function parameters. Best I could come up with is using reflection to obtain some metadata about functions and classes, although that solution is not perfect...
MathWorks seems to be using their own internal system to author HTML documentation. Too bad they don't share it with us users :)
Solution 2
I think this is the officially santioned Mathworks' way of writing documentation: http://www.mathworks.co.uk/help/matlab/matlab_prog/display-custom-documentation.html
Basically write the HTML, and add a bunch of files to make it searchable and displayable in the MATLAB documentation.
Solution 3
there is an easy way to use publish with a function & it's corresponding inputs. look at publish('test',struct('codeToEvaluate','test(inputs);','showCode',false,
))
.
Related videos on Youtube
Lukas
Updated on June 25, 2022Comments
-
Lukas about 2 years
I am working on shared Matlab code and we would like to share a generated documentation as searchable HTML documents within our local network.
I know of the following methods to generate a documentation:
- Write a converter to C++-like files. This is done in in Using Doxygen with Matlab (Last updated 2011) and mtoc++ (last updated 2013). The C++-like files are then parsed by Doxygen.
- Use Python's sphinxcontrib-matlabdomain to generate a HTML documentation.
- Use m2html which is also a third-party solution.
- Further options are listed in this Q&As: One, Two and Three.
All possibilities are not supported by Mathworks. All possibilities need me to mention i.e. the parameters of a function myself. They do not analyze the code in the sense, Doxygen does it for i.e. Java:
//! an object representation of the advertisement package sent by the beacon private AdvertisementPackage advertisementPackage;
I heard of Matlab's publish() function, but I did never see it used in the aforementioned sense.
Question: What is the Mathworks way to generate Matlab HTML documentation. Can the code itself be analyzed? Can I use the information provided to the Matlab Input Parser already? Please mention your personal preference in comments.
Example:
%% Input parser p = inputParser; addRequired(p, 'x', @isnumeric); validationFcn = @(x) (isnumeric(x) && isscalar(x)); addRequired(p, 'fftSize', validationFcn); addRequired(p, 'fftShift', validationFcn); validationFcn = @(x) (isa(x, 'function_handle')); addRequired(p, 'analysisWindowHandle', validationFcn); parse(p, x, fftSize, fftShift, analysisWindowHandle);
-
Mark Mikofski over 9 yearsTo clarify the matlabdomain Sphinx extension, authored by me, does analyze your code and automatically generate documents similar to Epydoc. Try using the
autosummary extension
to list your desired source, then usesphinx-autogen
to automatically generateautodoc
stub files, then build your docs. -
Lukas over 9 yearsWe now decided to take the Sphinx road as we recieved fast and good feedback when encountering problems.
-
Amro over 9 yearsI was snooping around MATLAB's HTML help files, and I noticed references to a product called Arbortext: en.wikipedia.org/wiki/Arbortext_Advanced_Print_Publisher
-
Lukas over 9 yearsCan you elaborate on this please? I see that I can write HTML files on my own. But do you see a way to generate those HTML files from information given in the source code (header, InputParser)?
-
am304 over 9 yearsThe only way to generate HTML from code as far as I know is to use the
publish
function with the MathWorks markup for the code. -
Lukas over 9 yearsAs far as I found out by now, it will execute the script. Most of the time I want to document functions and their input and not run them. Do you see a solution?
-
am304 over 9 yearsNo, sorry. It looks like
publish
only works for scripts, and executes the script to generate the HTML. If you want to go down that route, you'll need to write a script (it can be mostly marked-up comments) that is essentially your documentation, with a little bit of code that calls your function to generate an example of how to call the function in the doc.