Adding help and demos to the Help browser
Contents
Introduction
This document is a short guide to adding your own toolbox to the Help browser. For further details please see Adding Your Own Toolboxes to the Development Environment under MATLAB Help.
There are a number of example files accompanying this guide. You should have the following directory structure:
In addition to this example further help can be found in the online MATLAB documentation.
Creating help
In this example we demonstrate the use of M2HTML to automatically generate MATLAB M-file and toolbox documentation in HTML. The usefulness of the generated documentation will depend upon the quality of the comments and help text which accompany each function. Here are a few references on how to document functions:
The first step is to download M2HTML from MATLAB Central.
Extract M2HTML and add to your MATLAB path.
In this example the toolbox is made up of a collection of functions which are contained in the m_files directory. To run M2HTML change directory to the level above m_files. Run the following command at the command line:
>> m2html('mfiles','m_files','htmldir','doc')
This will generate HTML documentation and place this in the directory doc. Example output documentation from M2HTML can already be found in the doc directory.
Adding HTML documentation to the Help browser
MATLAB determines what information to display in the MATLAB Start Menu and Help browser using info.xml files; the info.xml file must be in a directory on the search path or in the current directory.
An example info.xml file is provided in the top level directory of this example. Its contents are displayed below.
The following information should be changed when working with your own toolbox:
- matlabrelease - latest release of MATLAB with which the toolbox is compatible
- name - name of your toolbox
- help_location - location of the directory containing your help files
In this example the help files are located in the doc directory.
For additional information on the info.xml file please consult the relevant MATLAB help page.
In the directory containing your help files you require a helptoc.xml file. An example is provided in the doc directory. Its contents are shown below.
The text should be changed to reflect the name of your toolbox. The example helptoc.xml has index.html as a target. This is the HTML page displayed when the user selects the toolbox in the Help browser. M2HTML generates a top-level page with this name by default.
Making your help searchable
To create a searchable database; run the command
>> builddocsearchdb(full_path_to_help_dir)
where the argument is the fully specified path (not relative) to the directory containing your help files, e.g. C:\work\tracking_toolbox\doc. This will create a helpsearch directory under your help directory.
Updating the Help browser
The final step is to allow the Help browser to see your HTML help files. Make sure the info.xml file is present on the MATLAB path. See this page for more information on setting the path.
To ensure that the help displayed by MATLAB is up-to-date you should complete the following steps:
- Select Start > Desktop Tools > View Start Button Configuration Files.
- In the resulting Start Button Configuration Files dialog box, click Refresh Start Button. This refreshes info.xml files for MATLAB.
You may now access help for your toolbox through the Help browser.
Creating a demo
Collect together the necessary files required to run your demo in a directory. In this example the directory is called demo. It is common to provide an HTML file to describe the demo. The easiest way to do this is with MATLAB's publishing functionality. This can be accessed from the command line with the function publish as well as through an editor toolbar.
The example provided was published from the file AbandonedObjectDetection.m which is also included in the directory demo. The result of publishing this M-file is an HTML file in the directory demo/html.
Similarly to info.xml providing demos for your toolbox requires a demos.xml. You must ensure that demos.xml is in the MATLAB path. An example is provided and is shown below.
There are several items you may wish to change. Most are straightforward names. In general a demosection can contain multiple demoitems which can be useful if you wish to organise multiple demos. The two most important items to change are:
- file - published HTML file described above. This is what the user will see when they click on the demo in the Help browser. In this example it is AbandonedObjectDetection.html
- callback - MATLAB script/function run when the user click Run Demo. In this example it is AbandonedObjectDetection.m
The result of adding the example demo to the Help browser is shown below.
