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

Обзор

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

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

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

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

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

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

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

Создание info.xml Файл

The 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 Файл

The 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, чтобы просмотреть результаты для тулбокса.

Начиная с R2014b MATLAB, вы можете поддерживать поисковые индексы один за другим. Например, если у вас уже есть индекс поиска для MATLAB R2014a или ранее, запустите builddocsearchdb против файлов справки с помощью R2014b MATLAB. Затем при запуске любого релиза 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.