Документация

Обзор

При создании панели инструментов, работающей с продуктами MathWorks ®, даже если она содержит только несколько функций, можно включить пользовательскую документацию в виде HTML-файлов справки. Пользовательская документация для панели инструментов может включать рисунки, диаграммы, снимки экрана, уравнения и форматирование, чтобы сделать панель инструментов более удобной для использования.

Для правильного отображения пользовательская документация должна содержать следующие файлы:

Чтобы просмотреть пользовательскую документацию, откройте браузер справки и перейдите на домашнюю страницу. В нижней части главной страницы в разделе Дополнительное программное обеспечение щелкните имя панели инструментов. Справка откроется в текущем окне.

Создание файлов справки HTML

HTML-файлы справки можно создавать в любом текстовом редакторе или ПО веб-публикации. Для создания файлов справки в MATLAB используйте один из следующих методов:

Храните все файлы справки HTML в одной папке, например html вложенная папка в папке панели инструментов. Эта папка должна быть:

Наборы документации часто содержат:

Создать info.xml Файл

info.xml В файле описывается пользовательская документация, включая имя, отображаемое для документации. Он также определяет, где найти файлы справки HTML и helptoc.xml файл. Создание файла с именем info.xml для каждой панели инструментов, которую вы документируете.

Создать info.xml для описания панели инструментов можно адаптировать этот шаблон:

<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')

В следующей таблице описаны необходимые элементы info.xml файл.

Вы также можете включить комментарии в info.xml файл, например, авторские права и контактная информация. Создание комментариев путем включения текста в строку между <!-- и -->.

При создании info.xml убедитесь, что:

Создать helptoc.xml Файл

helptoc.xml файл определяет иерархию файлов справки, отображаемых на панели «Содержимое» браузера дополнительного программного обеспечения.

Можно создать helptoc.xml с помощью шаблона, включенного в документацию MATLAB. Создание и редактирование копии файла шаблона helptoc_template.xml в текущей папке запустите этот код в окне команд:

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

Разместить helptoc.xml в папке, содержащей файлы документации HTML. На эту папку необходимо ссылаться как <help_location> в вашем info.xml файл.

Каждый <tocitem> запись в helptoc.xml ссылается на один из файлов справки HTML. Первое <tocitem> запись в helptoc.xml файл служит начальной целевой страницей для документации.

В пределах верхнего уровня <toc> элемент, вложенный <tocitem> элементы определяют структуру оглавления. Каждый <tocitem> элемент имеет target атрибут, предоставляющий имя файла. Имена файлов и путей чувствительны к регистру.

При создании helptoc.xml убедитесь, что:

<?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>

Создание базы данных поиска

Чтобы сделать документацию доступной для поиска, создайте базу данных поиска, также называемую индексом поиска, с помощью builddocsearchdb команда. При использовании этой команды укажите полный путь к папке, содержащей файлы HTML.

Например, предположим, что файлы HTML находятся в C:\MATLAB\MyToolbox\html. Эта команда создает базу данных с возможностью поиска для этих файлов:

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

builddocsearchdb создает подпапку C:\MATLAB\MyToolbox\html названный helpsearch-v3, который содержит файлы базы данных.

Для поиска терминов в панели инструментов откройте обозреватель справки и в поле Поиск документации введите термин, который требуется найти. Затем в левой части страницы в разделе Уточнить по источнику (Refine by Source) выберите Дополнительное программное обеспечение (Additional Software), чтобы просмотреть результаты для панели инструментов.

Начиная с MATLAB R2014b, можно вести индексы поиска бок о бок. Например, если индекс поиска для MATLAB уже существует R2014a или ранее, выполните команду builddocsearchdb для файлов справки с помощью MATLAB R2014b. Затем при запуске любой версии MATLAB браузер справки автоматически использует соответствующий индекс для поиска в базе данных документации.

Ошибки проверки адреса для info.xml Файлы

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.