Documentation format

MATLAB code documentation format

The MATLAB toolboxes are documented using a very light touch markup language inspired by and inspired by Restructured Text. MATLAB code is parsed and documentation in MarkDown, LaTeX or HTML format by the help2doc, and the markup is described in that repo.

This markup provides headings (single level), lists (nestable), tables (2 colum), literal blocks and paragraphs. A design goal was for the markup to be subtle so when read using the MATLAB help function it was still very readable.

The documentation convention does not have explicit description of each input and output variable, that's done in prose in the first paragraph.

Python conventions

(spatialmath-python](https://github.com/petercorke/spatialmath-python) has adopted Sphinx for documentation, where comment blocks are highly-structured with intrusive markup in RestructuredText (RST) format. Other alternatives include Google documentation format and numpy documentation format.

However some IDEs provide automatic generation of the RST comment block and pre-populate it. The RST formatted docstrings are also used by IDEs to provide argument completion.

Impact on project

Considerable manual effort will be required to recycle the MATLAB documentation.

Workflow

• Use Python IDE to create first cut of RST formatted docstring for a method
• Cut and paste in the prose, tables and lists from the MATLAB documentation, adding RST markup where appropriate, eg. double back-ticks to indicate function, method or variable names.
• Extend the documentation with equations which are possible using the :math role.