10.4. Как написать статью

Каждая статья должна содержать:

• Краткое введение.

• Примеры.

• Содержание статьи должно быть от одной то двух страниц текста (включая примеры). Если представиться возможность написать статью большего объёма, то это всегда приветствуется.

• Статья должна быть оформлена при помощи reStructuredText (заголовки, таблицы, фрагменты кода и т. п.), для того, чтобы её в дальнейшем было удобнее читать.

• Каждая глава в статье должна быть оформлена при помощи специально для этого предназначенного reStructuredText.

• При описании набора параметров у которых есть название и тип входного значения (напр. параметры тэгов, блоков, методов) нужно использовать шаблон .. config-property::. Если данный список параметров не находиться в таблице, то его нужно в таковую поместить (только чтобы не получилось вложенных таблиц).

  .. config-property::
     :name: property-name
     :type: property-type
     :ref_prefix: optional_reference_prefix_
  

10.4.1. Форма изложения

• Если нужно описать действия самой системы, то это нужно делать в третьем лице, напр. откроется окно, заполнятся поля, система выдаст сообщение.

• Если нужно указать на требуемые действия, то это должно делаться в неопределенной форме, напр. надо нажать, кнопку, можно выбрать значение, желательно указать причину.

• Глаголы, употребляемые в статье (и предложения, в которых они используются) должны использоваться в 3-ем лице или в безличной (неопределённой) форме.

• Следует избегать обращений в духе «Ты», «Вы», «Мы» и подобных (см. правила русского языка).

10.4.2. Заголовки

• Для создания глав в статье используются заголовки:

  #########
  Part name
  #########
  
  ************
  Chapter name
  ************
  
  Section name
  ============
  
  Subsection name
  ---------------
  
  Subsubsection name
  ^^^^^^^^^^^^^^^^^^
  
  Paragraph name
  """"""""""""""
  

• Все заголовки в статье должны называться с большой буквы.

10.4.3. Изображения

• Если в статье используются изображения, то нужно пользоваться их эскизами (thumbnail), а не полными версиями.

  .. image:: /images/sample_image.jpg
     :width: 120px
  

• Каждое изображение в статье должно содержать краткое описание для screen readers.

  .. image:: /images/sample_image.jpg
     :width: 120px
     :alt: sample image description
  

• Изображение в статье может содержать краткое описание для человека.

  .. figure:: /images/sample_image.jpg
     :figwidth: 120px
     :width: 120px
     :alt: sample image description for screen reader
  
     sample image description for human
  

• Если на изображении видна строка ввода адреса браузера, то её содержание показывать не нужно (т.е. нужно затереть). Кроме случаев, когда эта информация используется в статье.

10.4.4. Примеры

• Должны присутствовать примеры использования описываемого материала, т.к. это облегчает его понимание.

• Количество примеров должно быть достаточным для понимания изложенного материала.

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

• Примеры, используемые в тексте статьи должны быть, по возможности, согласованы между собой и текстом статьи.

• Примеры должны быть специальным образом оформлены, напр. если это код, то его нужно оформлять так:

  .. code:: language
  
     code goes here
  

• Примеры должны находиться в тех местах статьи, в которых они упоминаются (обычно сразу после или рядом с текстом, описывающем пример).

• Примеры должны быть объединены с текстом статьи, а не находиться в отдельных главах.

10.4.5. Внутренние ссылки

• Если упомянутый в статье материал описан подробнее в другой статье, то на него должна быть дана внутренняя ссылка. Таким образом повышаются шансы, что человек читающий эту статью также прочтёт и ту статью, на которую ведёт внутренняя ссылка. Напр.

  • :doc:`текст </path/to/other/article>` - ссылка будет с указанным текстом;

  • :doc:`/path/to/other/article` - ссылка будет с название статьи.

• Если требуется сослаться на другую часть материала в той-же статье, то нужно:

  1. над заголовком добавить метку .. _this_is_a_mark;

  2. использовать один из вариантов создания ссылки:

     • :ref:`текст <this_is_a_mark>` - ссылка будет с указанным текстом;

     • :ref:`this_is_a_mark` - ссылка будет с названием заголовка.

• Если в статье упоминаются термины, о которых уже написаны статьи, то упоминание этих терминов также нужно оформлять как внутренние ссылки. Но не более чем 1 раз на параграф текста.

• Если в статье упоминаются термины, про которые статей ещё не написано, но скорее всего будут, то для них нужно:

  1. создать пустую страницу с заголовком;

  2. поместить её в оглавление;

  3. оформить как внутренние ссылки.

10.4.6. Статьи с описанием таблиц

На статьи с описанием таблиц в базе данных накладываются дополнительные правила по оформлению и содержанию.

• Статья должна находиться в паке /docs/database/table_structure.

• Статья должна называться также как и таблица, которую она описывает (без префикса таблиц базы данных), напр. ConfigurationAdmin.

• Описание полей должно быть оформлено в виде таблицы (см. категорию Структура таблиц).

• Название каждого поля должно быть выведено, используя шаблон .. config-property::.

• Все связанные с описываемой таблицей статьи (которые тоже описывают таблицы, т.е. из категории Структура таблиц) должны быть указаны в разделе См. также в конце статьи.

• Если при описании полей таблицы упоминались другие таблицы, то:

  • такие таблицы должны присутствовать в разделе См. также в конце статьи;

  • каждое упоминание другой таблицы должно быть ссылкой на статью о ней;

  • каждое упоминание одного поля этой таблицы в описании другого поля должно быть ссылкой на описание первого (напр. :ref:`tc_SameTable_SameTableField`);

  • каждое упоминание поля другой таблицы в описании поля этой таблицы должно быть ссылкой на описание первого, напр. :ref:`tc_OtherTable_OtherTableField`;

• Если из названия или описания поля нельзя однозначно понять, что в нём храниться, то обязательно надо привести пример с возможными значениями данного поля.

Совет

Примеры корректного оформления статей с описанием таблиц базы данных можно найти в статьях из категории Структура таблиц.

10.4.7. Статьи с описанием событий

На статьи с описанием событий накладываются дополнительные правила по оформлению и содержанию:

• для каждого события написать описание;

• для каждого события написать события (в виде внутренних ссылок), из которых оно вызывается (обратная ссылка) и при каких обстоятельствах;

• если в событие при вызове передаются входные параметры (доступные через $event->getEventParam), то их тоже нужно описать;

• если событие при своей работе вызывает другие события (напр. OnSave вызывает OnPreSave), то это нужно указать (прямая ссылка) и при каких обстоятельствах;

• описать потенциальное применение каждого события, т.е. для чего оно сделано, когда использовать;

• написать (если таковые имеются) ограничения при использовании событий, напр.

  • что OnCreate не связан на прямую с OnBeforeItemCreate;

  • для изменения данных в объекте нужно использовать событие OnBeforeItemCreate, а не OnCreate;

• если событие после своего успешного выполнения закрывает всплывающее окно (popup), напр. OnCreate, то это нужно указать;

• если событие использует temp handler для манипуляций со временными таблицами (напр. OnPreCreate), то это нужно указать;

• если событие использует вспомогательные методы того класса (напр. OnEdit использует метод StoreSelectedIds), где оно объявлено, то их нужно указать (можно их самих не описывать);

• если событие будет вызвано, т.к. его название было передано с формы в результате действий пользователя, то нужно описать при каких обстоятельствах это происходит (напр. OnSave);

• если событие применяется только в административной консоли (напр. OnSave) или только на пользовательской части сайта (напр. OnSetSortingDirect) то это нужно указать.

10.4.8. Статьи с описанием ошибок

В статьях с описанием нужно будет осветить следующие аспекты:

• описать каждое сообщение об ошибке;

• указать откуда они вызываются (не только название класса и метод в нём, но и словами написать что в этом методе происходит);

• указать что нужно сделать, чтобы получить конкретное сообщение об ошибке;

• дать рекомендации о том, как нужно писать код, чтобы не было сообщения об ошибке;

Статья должна состоять из ряда глав (по главе на каждую ошибку). Каждая глава в свою очередь будет состоять из под-глав, описанных ниже.

Название ошибки (по смыслу)
---------------------------
Текст ошибки (реальный пример, скопированный из отчёта отладчика.

Вызов ошибки
^^^^^^^^^^^^
Какой код вызывает данную ошибку и почему.

Получение ошибки
^^^^^^^^^^^^^^^^
Что нужно сделать, чтобы была вызвана данная ошибка.

Исправление ошибки
^^^^^^^^^^^^^^^^^^
Что нужно сделать, чтобы данная ошибка больше не происходила, т.е. чтобы её исправить.

См. также

• https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

• https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst

• https://docutils.sourceforge.io/docs/ref/rst/directives.html