functions to help extract .mbedded source doc; +export to .md
helpDocMd aims to provide an easy pipeline for publishing custom MATLAB® documentation:
-
particularly class-based API documentation
-
specifically as Markdown to be readily hosted online (1, 2, 3).
- MATLAB® Version R2019b or later.
-
Clone this repository or download the source code.
-
Start up Matlab and add the downloaded 'src' directory along with its subfolders to the path by typing
addpath( genpath( '.../src/' )); which('Documentor')into the command prompt (replacing the ellipsis with the path to the downloaded folder). The filepath to Documentor.m should be displayed.
The first and most difficult step to publishing your source code documentation: Write it! (specifically, the header comment).
To publish it, the process is simple:
-
Assemble the list of .m files and/or code-containing directories that you want to include as entries in a string vector: let's call it
src. (By default, ifsrcis a directory, it will be searched recursively for documentable .m files.) -
Initialize a
Documentorobject (e.g. one calledDr) with your list:
Dr = Documentor( src ) ;
- To print all of the documentation to Markdown text files, call:
Dr.printdoc( ) ;
To print the documentation for the Documentor class itself:
Dr = Documentor( which('Documentor') ) ;
Dr.printdoc( ) ;
If successful, the .md file path is displayed in the command window.
Once formated to HTML on GitHub, it looks like this.
—A fake FAQ:
What's wrong with the built-in
helpanddoccommands?
Both are very useful, and the recently introduced Live Editor has great publishing features for scripts, but as of 2020(a) there still isn't any built-in functionality to export class documentation.
There are advantages—simplicity, +potentially
automating
some of the documentation itself—to keeping the software and the commenting
syntax
"in-house"; particularly if we can assume
that the built-in publishing features will eventually be extended to classes.
(Albeit, the doc command already generates the—yet private—HTML that users
have been requesting for years (4, 5) so who knows...)
- Test a Markdown sample for how it will display once reformatted to HTML.
Re: hosting documentation online:
Same for parent repo: realtime_shimming