Если вы создаете тулбокс, который работает с продуктами MathWorks®, даже если он только содержит несколько функций, можно включать пользовательскую документацию в форме справочных файлов HTML. Пользовательская документация для вашего тулбокса может включать фигуры, схемы, снимки экрана, уравнения, и форматирующий, чтобы заставить ваш тулбокс помочь более применимый.
Чтобы отобразиться правильно, ваша пользовательская документация должна содержать эти файлы:
Справочные файлы HTML — Эти файлы содержат вашу пользовательскую информацию о документации.
info.xml
файл — Этот файл позволяет MATLAB® найти и идентифицировать ваши справочные файлы HTML.
helptoc.xml
файл — Этот файл содержит Оглавление для вашей документации, которая отображается в панели Contents Браузера документации. Этот файл должен храниться в папке, которая содержит ваши справочные файлы HTML.
Поисковая (дополнительная) база данных — Эти файлы позволяет искать в ваших справочных файлах HTML.
Чтобы просмотреть вашу пользовательскую документацию, откройте Браузер документации и перейдите к домашней странице. В нижней части домашней страницы, под Supplemental Software, кликают по имени вашего тулбокса. Ваша справка открывается в активном окне.
Можно создать справочные файлы HTML в любом текстовом редакторе или программном обеспечении веб-публикаций. Чтобы создать справочные файлы в MATLAB, используйте любой из этих двух методов:
Создайте live скрипт (*.mlx
) и экспортируйте его в HTML. Для получения дополнительной информации смотрите Live скрипты Доли и Функции.
Создайте скрипт (*.m
), и опубликуйте его в HTML. Для получения дополнительной информации смотрите, Публикуют и Доля код MATLAB.
Сохраните все свои справочные файлы HTML в одной папке, такие как html
подпапка в вашей папке тулбокса. Эта папка должна быть:
На пути поиска файлов MATLAB
Вне
папкаmatlabroot
Вне любого установленного оборудования поддерживают папку справки пакета
Наборы документации часто содержат:
Страница дорожной карты (то есть, начальная целевая страница для документации)
Примеры и темы, которые объясняют, как использовать тулбокс
Функционируйте или блокируйте страницы с описанием
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>
info.xml
при помощи шаблона info_template.xml
включенный с документацией MATLAB. Чтобы создать и отредактировать копию файла шаблона в вашей текущей папке, запустите этот код в командном окне:copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',... 'examples','templates','info_template.xml'),pwd) fileattrib('info_template.xml','+w') edit('info_template.xml')
Следующая таблица описывает необходимые элементы info.xml
файл.
XML-ТЭГ | Описание | Значение в шаблоне | Примечания |
---|---|---|---|
<matlabrelease> | Релиз MATLAB | R2016b | Указывает, когда вы добавили справочные файлы. Не отображенный в браузере. |
<name> | Заголовок тулбокса | MyToolbox | Имя, чтобы отобразить для вашей пользовательской документации в браузере панель Contents. |
<type> | Пометьте для тулбокса | toolbox | Допустимые значения: matlab , toolbox , simulink , blockset , links_targets Другой . |
<icon> | Значок для кнопки Start (не используемый) | 'none' | Больше используемый, но <icon> элемент все еще требуется для MATLAB проанализировать info.xml файл. |
<help_location> | Местоположение справочных файлов | html | Имя подпапки, содержащей helptoc.xml и справочные файлы HTML для вашего тулбокса. Если местоположение справки не является подпапкой info.xml расположение файла, задайте путь к help_location относительно info.xml файл. Если вы обеспечиваете справочные файлы HTML для нескольких тулбоксов, help_location в каждом info.xml файл должен быть различной папкой. |
<help_contents_icon> | Значок, чтобы отобразиться в панели Contents | 'none' | Проигнорированный в MATLAB R2015a и позже. Не вызывает ошибку, если это появляется в info.xml файл, но не требуется. |
Также можно включать комментарии в info.xml
файл, такой как авторское право и контактная информация. Создайте комментарии путем включения текста на линии между <!--
и -->
.
Когда вы создаете info.xml
файл, убедитесь что:
Вы включаете все необходимые элементы.
Записи находятся в том же порядке как в предыдущей таблице.
Имена файлов и имена папок в XML точно совпадают с именами ваших файлов и папок и использованы для своей выгоды тождественно.
info.xml
файл находится в папке на пути поиска файлов MATLAB.
Примечание
MATLAB анализирует info.xml
файл и отображения ваша документация, когда вы добавляете папку, которая содержит info.xml
к пути. Если вы создали info.xml
файл в папке уже на пути, удалите папку из пути. Затем добавьте папку снова, так, чтобы MATLAB проанализировал файл. Убедитесь, что папка, которую вы добавляете, не является вашей текущей папкой.
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
файл, убедитесь что:
Местоположение helptoc.xml
файлы перечислены как <help_location>
в вашем info.xml
файл.
Все имена файлов и пути точно совпадают с именами файлов и папок, включая капитализацию.
Все пути используют диафрагмы пути к файлу URL (/). Диафрагмы пути к файлу стиля Windows (\
) может заставить оглавление отображаться неправильно. Например, если у вас есть страница справки HTML firstfx.html
расположенный в подпапке под названием refpages
в основной папке документации, <tocitem>
target
значением атрибута для той страницы был бы refpages/firstfx.html
.
helptoc.xml
ФайлПредположим, что вы создали следующие файлы HTML:
Дорожная карта или начальная страница для вашего тулбокса, mytoolbox.html
.
Страница, которая перечисляет ваши функции, funclist.html
.
Три страницы ссылки на функцию: firstfx.html
, secondfx.html
, и thirdfx.html
.
Пример, myexample.html
.
Включайте имена файлов и описания в 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>
Этот helptoc.xml
файл, соединенный с правильно сформулированным info.xml
файл, произведенный это отображение в Браузере документации.
Чтобы сделать вашу документацию доступной для поиска, создайте поисковую базу данных, также называемую поисковым индексом, с помощью 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
Файлы Когда MATLAB находит info.xml
файл на пути поиска файлов или в текущей папке, это автоматически подтверждает файл против поддерживаемой схемы. Если существует недопустимое построение в info.xml
файл, MATLAB отображает ошибку в Командном окне. Ошибка обычно имеет форму:
Warning: File <yourxmlfile.xml> did not validate. ...
info.xml
ошибка валидации может произойти, когда вы запускаете MATLAB или добавляете папки в путь поиска файлов.
Первичные причины ошибки валидации XML-файла:
Сущности отсутствуют или не в порядке в info.xml
файл.
Несвязанный info.xml
файл существует.
Синтаксические ошибки в info.xml
файл.
MATLAB пытается получить доступ к устаревшему info.xml
файл для Продукта Mathworks.
Пропавшие без вести сущностей или не в порядке в info.xml
Если вы не перечисляете требуемые элементы XML в предписанном порядке, вы получаете ошибку валидации XML:
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.
info.xml
файл и их необходимое упорядоченное расположение, смотрите, Создают info.xml Файл.info.xml
ФайлПредположим, что у вас есть файл с именем info.xml
это не имеет никакого отношения к пользовательской документации. Поскольку этот info.xml
файл является несвязанным файлом, если он вызывает ошибку, можно безопасно проигнорировать его. Чтобы препятствовать тому, чтобы сообщение об ошибке повторялось, переименуйте несвязанный info.xml
файл. В качестве альтернативы гарантируйте, что файл не находится на пути поиска файлов или в текущей папке.
info.xml
Файл.Используйте сообщение об ошибке, чтобы изолировать проблему или использовать любой блок проверки допустимости XML-схемы. Для получения дополнительной информации о структуре info.xml
файл, консультируйтесь с его схемой в matlabroot
/sys/namespace/info/v1/info.xsd
.
info.xml
Файл для продукта MathworksЕсли у вас есть info.xml
файл от различной версии MATLAB, тот файл мог содержать построения, которые не допустимы с вашей версией. Идентифицировать info.xml
файл от другой версии, посмотрите на имена полного пути, о которых сообщают в сообщении об ошибке. Путь обычно включает номер версии, например, ...\MATLAB\R14\...
. В этой ситуации ошибка на самом деле не вызывает проблем, таким образом, можно безопасно проигнорировать сообщение об ошибке. Чтобы гарантировать, что ошибка не повторяется, удалите оскорбление info.xml
файл. В качестве альтернативы удалите устаревший info.xml
файл от пути поиска файлов и из текущей папки.