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

Обзор

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

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

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

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

Можно создать справочные файлы HTML в любом текстовом редакторе или программном обеспечении веб-публикаций. Чтобы создать справочные файлы в MATLAB, используйте любой из этих двух методов:

Сохраните все свои справочные файлы HTML и любые дополнительные пользовательские файлы документации (такие как PNG и файлы CSS) для вашего тулбокса в одной папке, такие как 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 файл задает иерархию справочных файлов, отображенных в панели 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, введите термин, который вы хотите искать. Затем на левой стороне страницы, под Refine by Source, выбирают Supplemental 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.