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>) в теле текста-справки использовать не следует.
При создании справки не следует полагаться на то, что читатель – опытный разработчик и хорошо знаком с тем, что делает ваша нода. Самое главное: ваша справка должна быть полезной.
См.также
Внешние ссылки
