m2docgen

This Toolbox converts the header of matlab code files into HTML documents and adds those to the matlab documentation.

Welcome to m2docgen

This program converts the header of matlab code files into HTML documents and adds those to the matlab documentation.

Installing:

After downloading you will find a MATLAB "Toolbox" File - ".mltbx". Double-click on it to install the toolbox in MATLAB.

Please Note: By installing the toolbox, the code will be stored in the default folder defined by MATLAB!

Getting Started

To export your own folder with code files to the matlab documentation, copy and modify the file run_m2docgen_example.m (located in the "help" folder) according to its header. At a minimum, change these options in the 'opts' structure :

1. .toolboxName - A custom name of your toolbox/folder
2. mFolder - total path to your toolbox/folder
3. outputFolder - total path to the folder where the documentation should be stored
4. excludeFolder - Optional: Exclude one/many folder name(s) of the documentation (exact folder name required, not path)
5. .toc - Optional: If empty, the documentation structure will be mirrored from the subfolder / real folder structure. If you want a custom structure, read "Your own toc structure".

The "header" of a function is defined as the comment lines that appears right after the function definition line and ends with the first line that ist NOT a comment line (e.g. emtpy line or code line).

Make sure that your code headers have a similar structure like the examples in the "Templates" folder.

It is highly recommended to create sections starting with "%%". These are displayed as blocks in the documentation.

Your own toc stucture

The menu on the left side of the matlab documentation is the "table of content" (toc) structure. By default (if no opts.toc is set), the folder structure will be used as basis for the menue/toc. However, this can be influenced by assigning a special cell to opts.toc. This allows you to merge folders, change folder names and their positions in the toc structure. Read the 'custom structure' help site for an example of how to define a custom structure for your documentation.

Customization

You can customize the resulting HTML documents by modifying the files in the "Templates" folder. For example, the header & footer text and the logo can be changed.

Tips

• m2docgen focuses on the headers of functions and not on the code. Thus code lines and comment-blocks inside a function will NOT be documented.
• The custom documentation is only visible in the matlab help center if the target export folder is added to the matlab path. m2docgen does this step for you, but it can never hurt to check...
• The conversion of matlab live scripts to html documents is really slow and does not follow the customisation settings, so avoid it when possible.
• This toolbox relies on "%%" to identify heading sections, so use them in the header to segment the documentation site.
• If you want to define a custom page for one of the table of content (TOC) headings, first define the heading in toc structure in the opts. Then create your custom live script and put it somewhere in the source folder. Make sure that the name of the toc heading and the live script name are compatible with matlabs variable naming scheme. Example: The first heading in the TOC structure is defined as "Welcome_to_m2docgen". I created a live script (this one) with the exact same name and put it somewhere in the source folder. If the toc name or file name would include spaces, then the associated file could not be assigned to this landing page.
• The generation of the search database sometimes fails. Go to the folder, where the info.xml is stored, move one folder up, remove the folder and subfolders from the active search path, add it back and then run the script again.
• On that note: Make sure to have m2docgen added to the matlab path before running it.

Example: Documentation of m2docgen

As an example, you can view the documentation of this toolbox. Make sure, that the toolbox folder is added to the search path! Open the MATLAB Documenation by typing "doc" in the Command Window. Scroll down in the "Contents" Menü. There should be a subheading called "Supplemental Software". Below this heading, you will find the "m2docgen Toolbox". Click on it and you will see the documenation generated by m2docgen. Note that you can also use the "Search Function" to search for functions.

If you want to test m2docgen - just run the script run_m2docgen_example.m (located in help folder). This will create the documentation. For testing you can then change some options or create your own toc structure.

Example: Function and Documentation

function out = doubled(in)
% Here is the short description
%% Syntax
%   out = doubled(in)
%% Input
%   in  [double] - value to be twiced
%% Output
%   out [double] - twice the input - 2*in
%% Disclaimer
%   (c) 2021
%

%% Code
out = 2*in;
end

In this example m2docgen will read and create a html file with the following information. Note: The Section "%% Code" will not be documented since the header ends with the empty line. As described above, m2docgen focuses on the documentation of the header only - not on the code.

Short Description

Here is the short description

Syntax

out = doubled(in)

Input

in [double] - value to be twiced

Output

out [double] - twice the input - 2*in

Disclaimer

(c) 2021

Support

A brief overview of the general structure of the m2docgen process can be found in the help folder.

When encountering problems you can either read this documentation or contact one of the following persons:

Technical Questions: Nils Böhnisch, M.Sc.

Technical Questions: Pierre Ollfisch, B.Sc.

Mail: [e-mail]

Disclaimer

Copyright (c) 2020 Nils Böhnisch, Pierre Ollfisch.

This file is part of m2docgen.

m2docgen is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation, either version 3 of the License, or

any later version. Also see the file "License.txt".