Node-RED:Создание нод/Руководство по созданию текста-справки

Материал из Онлайн справочника
Перейти к навигацииПерейти к поиску

Перевод: Максим Кузьмин
Проверка/Оформление/Редактирование: Мякишев Е.А.


Руководство по созданию текста-справки[1]

Когда пользователь выбирает ноду в рабочей области или «палитре», кликая по ней левой кнопкой мыши, справа на вкладке «Info» в боковой панели показывается ее текст-справка. Из нее пользователь узнает всю информацию, необходимую для использования этой ноды.

В этом руководстве мы расскажем, как структурировать эту справку, чтобы сохранить единообразие со справками других нод.

Секции текста-справки

В этой секции содержится краткое описание ноды. В ней должно быть не более 2-3 элементов <p>. Текст в первом элементе <p> будет использоваться во всплывающей подсказке, показываемой при наведении курсором на ноду в «палитре» редактора Node-RED.

Если у ноды есть входной порт, то в этой секции будут описаны свойства сообщения, используемого этой нодой. Здесь также можно рассказать о типах данных, используемых в каждом свойстве. Описание должно быть коротким – если описание свойств требует более подробного объяснения, то эти подробности лучше перенести в секцию «Details».

Если у ноды есть выходные порты, то здесь, как и в секции «Inputs», описываются свойства сообщений, отправляемых нодой. Если нода обладает несколькими выходными портами, для каждого из них можно создать отдельный список со свойствами.

В этой секции содержится более детальная информация о ноде. Здесь объясняется, как ею пользоваться, а также содержится дополнительная информация о ее входных и выходных портах.

В этой секции можно указать ссылки на внешние ресурсы вроде...

  • Любой релевантной дополнительной документации. Например, в тексте-справке для ноды «Template» есть ссылка на руководство по языку-шаблонизатору Mustache
  • Git-репозитория или npm-страницы ноды, где пользователь может прочесть дополнительную информацию о ноде

Текст-справка в картинках выше сделан с помощью вот этого HTML-кода:

<script type="text/x-red" data-help-name="node-type">
<p>Connects to a MQTT broker and publishes messages.</p>

<h3>Inputs</h3>
    <dl class="message-properties">
        <dt>payload
            <span class="property-type">string | buffer</span>
        </dt>
        <dd> the payload of the message to publish. </dd>
        <dt class="optional">topic <span class="property-type">string</span></dt>
        <dd> the MQTT topic to publish to.</dd>
    </dl>

 <h3>Outputs</h3>
     <ol class="node-ports">
         <li>Standard output
             <dl class="message-properties">
                 <dt>payload <span class="property-type">string</span></dt>
                 <dd>the standard output of the command.</dd>
             </dl>
         </li>
         <li>Standard error
             <dl class="message-properties">
                 <dt>payload <span class="property-type">string</span></dt>
                 <dd>the standard error of the command.</dd>
             </dl>
         </li>
     </ol>

<h3>Details</h3>
    <p><code>msg.payload</code> is used as the payload of the published message.
    If it contains an Object it will be converted to a JSON string before being sent.
    If it contains a binary Buffer the message will be published as-is.</p>
    <p>The topic used can be configured in the node or, if left blank, can be set
    by <code>msg.topic</code>.</p>
    <p>Likewise the QoS and retain values can be configured in the node or, if left
    blank, set by <code>msg.qos</code> and <code>msg.retain</code> respectively.</p>

<h3>References</h3>
    <ul>
        <li><a>Twitter API docs</a> - full description of <code>msg.tweet</code> property</li>
        <li><a>GitHub</a> - the nodes github repository</li>
    </ul>
</script>

Заголовки секций

Заголовок каждой секции обрамляется тегом <h3>. В секции «Details» должны быть подзаголовки, которые оформляются с помощью тега <h4>.

<h3>Inputs</h3>
...
<h3>Details</h3>
...
 <h4>A sub section</h4>
 ...

Свойства сообщений

Список свойств сообщения создается с помощью тега <dl>. В нем должен быть атрибут «class» со значением «message-properties».

Каждый пункт в списке состоит из пары тегов <dt> и <dd>.

Каждый тег <dt> содержит название свойства и опциональный тег <span class="тип_свойства">, где содержится информация о типе свойства. Если это опциональное свойство, в <dt> должен быть атрибут «class» со значением «optional».

В каждом теге <dd> содержится краткое описание свойства.

<dl class="message-properties">
    <dt>payload
        <span class="property-type">string | buffer</span>
    </dt>
    <dd> the payload of the message to publish. </dd>
    <dt class="optional">topic
        <span class="property-type">string</span>
    </dt>
    <dd> the MQTT topic to publish to.</dd>
</dl>

Несколько выходных портов

Если у ноды есть несколько выходных портов, у каждого из них, как уже говорилось выше, должен быть собственный список со свойствами. Эти списки должны быть обернуты тегом <ol> с атрибутом «class», в котором содержится значение <node-ports>.

Каждый пункт в списке должен содержать краткое описание выходного порта, после чего должен идти список <dl> со свойствами сообщения.

Примечание: Если у ноды только один выходной порт, его в тег <ol> оборачивать не нужно. Достаточно тега <dl>.


<ol class="node-ports">
    <li>Standard output
        <dl class="message-properties">
            <dt>payload <span class="property-type">string</span></dt>
            <dd>the standard output of the command.</dd>
        </dl>
    </li>
    <li>Standard error
        <dl class="message-properties">
            <dt>payload <span class="property-type">string</span></dt>
            <dd>the standard error of the command.</dd>
        </dl>
    </li>
</ol>

Общие правила

Когда вы рассказываете о каком-либо свойстве сообщения за пределами списка свойств сообщения, к нему нужно добавлять префикс «msg.», чтобы читатель ясно понимал, что это такое. Кроме того, все это вместе нужно обернуть тегом <code>.

The interesting part is in <code>msg.payload</code>.

Никаких других элементов разметки (например, <b>, <i>) в теле текста-справки использовать не следует.

При создании справки не следует полагаться на то, что читатель – опытный разработчик и хорошо знаком с тем, что делает ваша нода. Самое главное: ваша справка должна быть полезной.

См.также

Внешние ссылки