m2md Convert MATLAB .m docstring/help to Markdown

Contents

  • Usage Notes
  • Syntax
  • Description
  • Examples
  • Input Arguments
  • Name-Value Arguments
  • Output Arguments
  • Tips
  • See Also
  • Authors
  • TODO

Usage Notes

Note: this README was generated using m2md and uses syntax dependent on MATLAB®’s PUBLISH function. However, it requires the addition of the keyphrase %% ENDPUBLISH after the help/docstring to function. See the help for the PUBLISH function and the associated Topic pages for more information on styling. For example, start lines with 1 space to show regular text; 2 spaces for monospaced text; and 3 spaces for sample code. As much as possible, compatibility with both PUBLISH and HELP was maintained. This code is distributed as-is, but is accepting improvements (at least in 2023).

Syntax 

m2md(file)
m2md
m2md("m2md-this-directory")
m2md([])
m2md(file, Name, Value)
mdFile = m2md(file,___)
[mdFile,texFile] = m2md(file,___)

Description

m2md(file) converts the doctring or help of the specified MATLAB code file to a tex file and then into a Markdown file, using the functionality provided by PUBLISH and LATEX2MARKDOWN. It requires the addition of the keyphrase %% ENDPUBLISH after the help/docstring to function.

m2md converts all the .m files in the current directory (not in its subdirectories) using default specifications, and outputs the .tex and .md files in ./html. Contents.m, if it exists, is (by default) output in the current directory (but this can be overridden). If more than half of the .m files in the current directory have been converted to .md files and placed in a sub-directory, m2md will try to guess the default settings that have been used.

m2md("m2md-this-directory") uses the keyphrase “m2md-this-directory” to iterate over the MATLAB .m code files in the current directory. It can be combined with Name-Value pairs, and in particular with recursiveSearch. Contents.m, if it exists, is (by default) output in the current directory (but this can be overridden).

m2md([]) does the same as the above i.e. iterates over all the .m files in the current directory. This can be combined with Name-Value pairs e.g. to change the output destination.

m2md(file, Name, Value) converts the specified MATLAB file with options specified by one or more name,value pair arguments. For example, you can specify custom options for generating the .tex and .md files, where to output the .tex or .md files, the name of the .md file, or whether to delete the .tex file.

mdFile = m2md(file, _) converts the specified MATLAB file and returns the relative path of the resulting .md file. You can use this syntax with any of the input argument combinations in the previous syntaxes.

[mdFile, texFile] = m2md(file, _) converts the specified MATLAB file and returns the relative path of the resulting .md file and the full path of the .tex file. You can use this syntax with any of the input argument combinations in the previous syntaxes.

Examples 

m2md("m2md");
m2md("m2md", 'mdDir', '.', 'mdFilename', 'README', 'deleteTex', true);
m2md([], 'mdDir', 'DOCS', 'deleteTex', true, 'recursiveSearch', false);

Input Arguments 

file - MATLAB file name (character vector | string)
MATLAB file name, specified as a character vector or string. It should *NOT*
include the '.m' extension. *NOTE*: When publishing a file, this will
overwrite existing files in the target folders with the same name as `file`.

Name-Value Arguments

texOptions - Options to pass through to PUBLISH (cell array) Name-Value arguments to be passed through when calling PUBLISH. The default behaviour is to set the format to latex and turn off the display and evaluation of code. These can be changed if desired, but is likely to significantly harm performance. See the Name-Value Arguemnts of PUBLISH for more information.

mdOptions - Options to pass through to LATEX2MARKDOWN (cell array) Name-Value arguments to be passed through when calling LATEX2MARKDOWN. Note that there is currently NO option to turn off the Table of Contents - this is autogenerated by PUBLISH. See the Instructions/docs for LATEX2MARKDOWN / LIVESCRIPT2MARKDOWN for more information.

outputDir - Directory to create the tex and md files (string \ensuremath{|} character vector) Output folder to which the tex and md files are saved. If no folder is specified, these will be output to the default specified by PUBLISH, ./html.

texDir - Directory to create the tex file only (string \ensuremath{|} character vector) Output folder to which the tex file only is saved.

mdDir - Directory to create the md file only (string \ensuremath{|} character vector) Output folder to which the md file only is saved.

mdFilename - Name of the md file (string OR character vector) Output file name to which the md file is saved.

deleteTex - Flag to delete tex file (false (default) \ensuremath{|} true) Whether to delete the intermediary tex file, specified as true or false. If the tex file is deleted and its parent folder is empty, the parent folder will then be deleted too.

recursiveSearc - Flag to seach subdirectories when using "m2md-this-directory" (false (default) \ensuremath{|} true) Whether to additionally search and create .md files for .m files located in the subdirectories of the present directory.

contentsName - Filename to be used for Contents.m ('Contents' (default) \ensuremath{|} string \ensuremath{|} character vector) Filename used for Contents.m if using m2md("m2md-this-directory", _) or m2md([], _).

contentsDir - Directory to be used for Contents.m ('.' (default) OR string OR character vector) Directory used for Contents.m if using m2md("m2md-this-directory", _) or m2md([], _).

Output Arguments

mdFile - Relative path to .md file (string \ensuremath{|} character vector) The output filepath as generated by LATEX2MARKDOWN.

texFile - Full path to .tex file (character vector \ensuremath{|} string) The output filepath as generated by PUBLISH.

Tips

  • In order to demarcate the end of the docstring: create a section entitled ENDPUBLISH (use %% ENDPUBLISH) i.e. %%, followed by a space, followed by ENDPUBLISH.

See Also 

PUBLISH, HELP, LOOKFOR
latex2markdown / livescript2markdown

Authors

Mehul Gajwani, Monash University, 2023

TODO

  • Add option to use m2md-this-directory to target another directory (i.e. other than the current directory)
  • Consider adding option to remove ToC
  • Review where outputs are produced (relative vs absolute locations)
  • Some potential issues when passing in full hyperlinks - can currently be worked around by putting them in code blocks using backticks