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

Обзор

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

Чтобы отобразиться правильно, ваша пользовательская документация должна содержать эти файлы:

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

Создание справочных файлов 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')

Создание файла helptoc.xml

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

Можно создать файл 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, который содержит файлы базы данных.

Можно искать условия в тулбоксе от поля Search Documentation в Браузере документации.

Начиная с 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.