Отображение пользовательской документации

Панорама

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

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

  • Справочные файлы HTML — Эти файлы содержат вашу пользовательскую информацию о документации.

  • info.xml файл — Этот файл позволяет MATLAB® найти и идентифицировать ваши справочные файлы HTML.

  • helptoc.xml файл — Этот файл содержит Оглавление для вашей документации, которая отображается в панели Contents Браузера документации. Этот файл должен храниться в папке, которая содержит ваши справочные файлы HTML.

  • Поисковая (дополнительная) база данных — Эти файлы позволяет искать в ваших справочных файлах HTML.

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

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

Можно создать справочные файлы 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>Релиз MATLABR2016bУказывает, когда вы добавили справочные файлы. Не отображенный в браузере.
<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 в Браузере документации.

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

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

Что такое ошибки валидации 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 файл от пути поиска файлов и из текущей папки.

Похожие темы

Для просмотра документации необходимо авторизоваться на сайте