Display Custom Documentation - MATLAB & Simulink (original) (raw)
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:
- HTML help files — These files contain your custom documentation information.
info.xmlfile — This file enables MATLAB® to find and identify your HTML help files.helptoc.xmlfile — This file contains the Table of Contents for your documentation that displays in the Contents pane of the MathWorks documentation home page. This file must be stored in the folder that contains your HTML help files.- Search database (optional) — These files enable searching in your HTML help files.
To view your custom documentation, open your system web browser and navigate to the MathWorks documentation home page. On the left side of the home page, clickSupplemental Software.
Then, click the name of your toolbox. Your documentation opens in the current tab of your system browser.
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:
- Create a live script (
*.mlx) and export it to HTML. For more information, see Ways to Share and Export Live Scripts and Functions. - Create a script (
*.m), and publish it to HTML. For more information, see Publish and Share MATLAB Code.
Store all your HTML help files for your toolbox and any additional custom documentation files referenced by your HTML help files (such as PNG, CSS, and JS files) in one folder, for example, an html subfolder in your toolbox folder.
This folder must be:
- On the MATLAB search path
- Outside the
_`matlabroot`_folder - Outside any installed hardware support package help folder
Documentation sets often contain:
- A roadmap page (that is, an initial landing page for the documentation)
- Examples and topics that explain how to use the toolbox
- Function or block reference pages
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, copy this template code into a new file, save it as info.xml, and then adapt the template for your toolbox:
<productinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="optional">
<?xml-stylesheet type="text/xsl"href="optional"?>
<!-- info.xml file for the mytoolbox toolbox -->
<!-- Version 1.0 -->
<!-- Copyright (date) (owner).-->
<!-- Supply the following six elements in the order specified -->
<!-- (Required) Release of MATLAB. Not currently used but required -->
<!-- to parse the file -->
<matlabrelease>R2016b</matlabrelease>
<!-- (Required) Title of toolbox. Appears in the Contents pane -->
<name>MyToolbox</name>
<!-- (Required) Label for the toolbox. pick one: -->
<!-- matlab, toolbox, simulink, blockset, links_targets -->
<type>toolbox</type>
<!-- (Required) Icon file to display in the Start button. Not currently used -->
<!-- but required to parse the file -->
<icon></icon>
<!-- (Required if you supply help) Relative path to help (HTML) folder -->
<help_location>html</help_location>
<!-- (Required if you supply help) Icon used in the Help browser TOC -->
<!-- Ignored in R2015a and later -->
<help_contents_icon></help_contents_icon>
</productinfo>The following table describes the required elements of theinfo.xml file.
| XML Tag | Description | Value in Template | Notes |
|---|---|---|---|
| Release of MATLAB | R2016b | Indicates when you added help files. Not displayed in the browser. | |
| Title of toolbox | MyToolbox | The name to display for your custom documentation in the browserContents pane. | |
| Label for the toolbox | toolbox | Allowable values: matlab,toolbox, simulink,blockset, links_targets,other. | |
| Icon for the Start button (not used) | none | No longer used, but the element is still required for MATLAB to parse the info.xml file. | |
| <help_location> | Location of help files | html | Name of the subfolder containing helptoc.xml, HTML help files, and any other custom documentation files (such as PNG and CSS files) for your toolbox. If the help location is not a subfolder of the info.xml file location, specify the path to help_location relative to theinfo.xml file. If you provide HTML help files for multiple toolboxes, the help_location in eachinfo.xml file must be a different folder. |
| <help_contents_icon> | Icon to display in Contents pane | none | Ignored in MATLAB R2015a and later. Does not cause error if it appears in the info.xml file, but is not required. |
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:
- You include all required elements.
- The entries are in the same order as in the preceding table.
- File and folder names in the XML exactly match the names of your files and folders and are capitalized identically.
- The
info.xmlfile is in a folder on the MATLAB search path.
Note
MATLAB parses theinfo.xmlfile and displays your documentation when you add the folder that containsinfo.xmlto the path. If you created aninfo.xmlfile in a folder already on the path, remove the folder from the path. Then add the folder again, so that MATLAB parses the file. Make sure that the folder you are adding is not your current folder.
Create helptoc.xml File
The helptoc.xml file defines the hierarchy of documentation files displayed in the Contents pane of the MathWorks documentation home page.
To create a helptoc.xml file, copy this template code into a new file, save it as helptoc.xml, and then adapt the template for your toolbox:
<?xml version='1.0' encoding="utf-8"?>
<toc version="2.0">
<!-- First tocitem specifies top level in Help browser Contents pane -->
<!-- This can be a roadmap page, as shown below, or a content page -->
<tocitem target="mytoolbox_product_page.html">MyToolbox Toolbox
<!-- Nest tocitems to create hierarchical entries in Contents-->
<!-- To include icons, use the following syntax for tocitems: -->
<!-- <tocitem target="foo.html" image="HelpIcon.NAME"> -->
<!-- Title-of-Section </tocitem> -->
<!-- where NAME is one of the following (use capital letters): -->
<!-- FUNCTION, USER_GUIDE, EXAMPLES, BLOCK, GETTING_STARTED, -->
<!-- DEMOS, RELEASE_NOTES -->
<!-- Icon images used for these entries are also stored in -->
<!-- matlabroot/toolbox/matlab/icons -->
<!-- A Getting Started Guide usually comes first -->
<tocitem target="mytbx_gs_top.html" image="HelpIcon.GETTING_STARTED">
Getting Started with the MyToolbox Toolbox
<tocitem target="mytbx_reqts_example.html">System Requirements
</tocitem>
<tocitem target="mytbx_features_example.html">Features
<!-- 2nd and lower TOC levels usually have anchor IDs -->
<tocitem target="mytbx_feature1_example.htm#10187">Feature 1
</tocitem>
<tocitem target="mytbx_feature2_example.htm#10193">Feature 2
</tocitem>
</tocitem>
</tocitem>
<!-- User Guide comes next -->
<tocitem target="mytbx_ug_intro.html"
image="HelpIcon.USER_GUIDE">MyToolbox User Guide
<tocitem target="mytbx_ch_1.html">Setting Up MyToolbox
</tocitem>
<tocitem target="mytbx_ch_2.html">Processing Data
</tocitem>
<tocitem target="mytbx_ch_3.html">Verifying MyToolbox outputs
<tocitem target="mytbx_ch_3a.html">Handling Test Failures
</tocitem>
</tocitem>
</tocitem>
<!-- Function reference next -->
<!-- First item is page describing function categories, if any -->
<tocitem target="helpfuncbycat.html"
image="HelpIcon.FUNCTION">Function Reference
<!-- First category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#1">First Category
<!-- Inside category, list its functions alphabetically -->
<tocitem target="function_1.html">function_1</tocitem>
<tocitem target="function_2.html">function_2</tocitem>
<!-- ... -->
</tocitem>
<!-- Second category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#2">Second Category
<!-- Inside category, list its functions alphabetically -->
<tocitem target="function_3.html">function_3</tocitem>
<tocitem target="function_4.html">function_4</tocitem>
<!-- ... -->
</tocitem>
<!-- Third category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#3">Third category
<!-- ... -->
</tocitem>
</tocitem>
<!-- Optional List of Examples, with hyperlinks to examples in other files -->
<tocitem target="mytbx_example.html"
image="HelpIcon.HelpIcon.EXAMPLES">Mytoolbox Examples
</tocitem>
<!-- Optional link or links to your or other Web sites -->
<tocitem target="http://www.mathworks.com"
image="$toolbox/matlab/icons/webicon.gif">
MyToolbox Web Site (Example only: goes to mathworks.com)
</tocitem>
</tocitem>
</toc>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 thehelptoc.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 atarget attribute that provides the filename. File and path names are case-sensitive.
When you create the helptoc.xml file, make sure that:
- The location of the
helptoc.xmlfiles is listed as the<help_location>in yourinfo.xmlfile. - All file and path names exactly match the names of the files and folders, including capitalization.
- All path names use URL file path separators (/). Windows style file path separators (
\) can cause the table of contents to display incorrectly. For example, if you have an HTML help pagefirstfx.htmllocated in a subfolder calledrefpageswithin the main documentation folder, the<tocitem>targetattribute value for that page would berefpages/firstfx.html.
Example helptoc.xml File
Suppose that you have created the following HTML files:
- A roadmap or starting page for your toolbox,
mytoolbox.html. - A page that lists your functions,
funclist.html. - Three function reference pages:
firstfx.html,secondfx.html, andthirdfx.html. - An example,
myexample.html.
Include filenames and descriptions in a helptoc.xml file as follows:
<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>This helptoc.xml file, paired with a properly formulatedinfo.xml file, produced this display in the documentation.
Build a Search Database
To make your documentation searchable, create a search database, also referred to as a search index, using the builddocsearchdb function. When using this function, specify the complete path to the folder that contains your HTML files.
For example, suppose that your HTML files are inC:\MATLAB\MyToolbox\html. This command creates a searchable database for those files:
builddocsearchdb('C:\MATLAB\MyToolbox\html')
builddocsearchdb creates a subfolder ofC:\MATLAB\MyToolbox\html namedhelpsearch-v4, which contains the database files.
To search for terms in your toolbox, open the MathWorks documentation in your system web browser and in the Search Documentation field, enter the term you want to search for. Then, on the left side of the page, under Refine by Source, selectSupplemental Software to view the results for your toolbox.
Beginning with MATLAB R2014b, you can maintain search indexes side by side. To ensure the documentation for the custom toolbox is searchable in a given release, runbuilddocsearchdb against your help files using that release of MATLAB. If you run builddocsearchdb using R2021b or a previous release, builddocsearchdb creates the subfolderhelpsearch-v3 to contain the search database files. Maintain both the helpsearch-v4 subfolder and thehelpsearch-v3 subfolder side by side. Then, when you run any MATLAB release, MATLAB automatically uses the appropriate database for searching your documentation.
Address Validation Errors for info.xml Files
What Are XML Validation Errors?
When MATLAB finds an info.xml file on the search path or in the current folder, it automatically validates the file against the supported schema. If there is an invalid construct in the info.xml file, MATLAB displays an error in the Command Window. The error is typically of the form:
Warning: File <yourxmlfile.xml> did not validate. ...
An info.xml validation error can occur when you start MATLAB or add folders to the search path.
The primary causes of an XML file validation error are:
- Entities are missing or out of order in the
info.xmlfile. - An unrelated
info.xmlfile exists. - Syntax errors in the
info.xmlfile. - MATLAB is trying to access an outdated
info.xmlfile for a MathWorks product.
Entities Missing or Out of Order in info.xml
If you do not list required XML elements in the prescribed order, you receive an XML validation error:
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.
For a description of the elements you need in an info.xml file and their required ordering, see Create info.xml File.
Unrelated info.xml File
Suppose that you have a file named info.xml that has nothing to do with custom documentation. Because thisinfo.xml file is an unrelated file, if it causes an error, you can safely ignore it. To prevent the error message from reoccurring, rename the unrelated info.xml file. Alternatively, ensure that the file is not on the search path or in the current folder.
Syntax Errors in the info.xml File
Use the error message to isolate the problem or use any XML schema validator. For more information about the structure of the info.xml file, consult its schema at_matlabroot_/sys/namespace/info/v1/info.xsd.
Outdated info.xml File for a MathWorks Product
If you have an info.xml file from a different version of MATLAB, that file could contain constructs that are not valid with your version. To identify an info.xml file from another version, look at the full path names reported in the error message. The path usually includes a version number, for example, ...\MATLAB\R14\.... In this situation, the error is not actually causing any problems, so you can safely ignore the error message. To ensure that the error does not reoccur, remove the offending info.xml file. Alternatively, remove the outdated info.xml file from the search path and out of the current folder.