Documentation

Overview

If you create a toolbox that works with MathWorks^® products, even if it only contains a few functions, you can include custom documentation in the form of HTML help files. Custom documentation for your toolbox can include figures, diagrams, screen captures, equations, and formatting to make your toolbox help more usable.

To display properly, your custom documentation must contain these files:

To view your custom documentation, open the Help browser and navigate to the home page. At the bottom right of the home page, under Supplemental Software, click the name of your toolbox. Your help opens in the current window.

Create HTML Help Files

You can create HTML help files in any text editor or web publishing software. To create help files in MATLAB, use either of these two methods:

Store all your HTML help files in one folder, such as an html subfolder in your toolbox folder. This folder must be:

Documentation sets often contain:

Create info.xml File

The info.xml file describes your custom documentation, including the name to display for your documentation. It also identifies where to find your HTML help files and the helptoc.xml file. Create a file named info.xml for each toolbox you document.

To create info.xml to describe your toolbox, you can adapt this template:

<productinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="optional">
    <?xml-stylesheet type="text/xsl"href="optional"?>
     
    <matlabrelease>R2016b</matlabrelease>
    <name>MyToolbox</name>
    <type>toolbox</type>
    <icon></icon>
    <help_location>html</help_location>
  
</productinfo>

copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',...
'examples','templates','info_template.xml'),pwd)
fileattrib('info_template.xml','+w')
edit('info_template.xml')

The following table describes the required elements of the info.xml file.

You also can include comments in your info.xml file, such as copyright and contact information. Create comments by enclosing the text on a line between <!-- and -->.

When you create the info.xml file, make sure that:

Create helptoc.xml File

The helptoc.xml file defines the hierarchy of help files displayed in the Contents pane of the Supplemental Software browser.

You can create a helptoc.xml file by using the template included with the MATLAB documentation. To create and edit a copy of the template file helptoc_template.xml in your current folder, run this code in the Command Window:

copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',...
'examples','templates','helptoc_template.xml'),pwd)
fileattrib('helptoc_template.xml','+w')
edit('helptoc_template.xml')

Place the helptoc.xml file in the folder that contains your HTML documentation files. This folder must be referenced as the <help_location> in your info.xml file.

Each <tocitem> entry in the helptoc.xml file references one of your HTML help files. The first <tocitem> entry in the helptoc.xml file serves as the initial landing page for your documentation.

Within the top-level <toc> element, the nested <tocitem> elements define the structure of your table of contents. Each <tocitem> element has a target attribute that provides the file name. File and path names are case-sensitive.

When you create the helptoc.xml file, make sure that:

<?xml version='1.0' encoding="utf-8"?>
<toc version="2.0">

    <tocitem target="mytoolbox.html">My Toolbox
        <tocitem target="funclist.html">Functions 
            <tocitem target="firstfx.html">first</tocitem>
            <tocitem target="secondfx.html">second</tocitem>
            <tocitem target="thirdfx.html">third</tocitem>
        </tocitem>
        <tocitem target="myexample.html">My Example
        </tocitem>
    </tocitem>

</toc>

Build a Search Database

To make your documentation searchable, create a search database, also referred to as a search index, using the builddocsearchdb command. When using this command, specify the complete path to the folder that contains your HTML files.

For example, suppose that your HTML files are in C:\MATLAB\MyToolbox\html. This command creates a searchable database for those files:

builddocsearchdb('C:\MATLAB\MyToolbox\html')

builddocsearchdb creates a subfolder of C:\MATLAB\MyToolbox\html named helpsearch-v3, which contains the database files.

You can search for terms in your toolbox from the Search Documentation field in the Help browser.

Beginning with MATLAB R2014b, you can maintain search indexes side by side. For instance, if you already have a search index for MATLAB R2014a or earlier, run builddocsearchdb against your help files using MATLAB R2014b. Then, when you run any MATLAB release, the help browser automatically uses the appropriate index for searching your documentation database.

Address Validation Errors for info.xml Files

Warning: File <yourxmlfile.xml> did not validate.
...

Often, errors result from incorrect ordering of XML tags. Correct the error by updating
the info.xml file contents to follow the guidelines in the MATLAB help documentation.