Руководство по стилю оформления

Эта страница покрывает соглашения по написанию и использованию разметки reStructuredText (RST).

Соглашения

  • Отступы в три пробела.

  • Строки должны быть короче 120 символов.

  • Для названий кнопок и меню следует использовать курсив.

Другие нестрогие соглашения:

  • Избегайте использования символов Юникода.

  • Избегайте слишком длинных предложений (располагающихся на нескольких строках).

Заголовки

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Примечание

Части (Document Part) должны использоваться только на страницах с содержанием или на заглавных страницах.

Примечание

Каждый файл .rst должен содержать только один заголовок главы (*).

Стилизация текста

См. обзор ReStructuredText для получения дополнительной информации о том, как стилизовать различные элементы документации и о том, как добавлять списки, таблицы, изображения и блоки кода. Справочник Sphinx предоставляет более подробную информацию о дополнительных конструкциях.

Для стилизации текста полезна следующая разметка:

*italic*
**bold**
``literal``

Элементы интерфейса

  • :kbd:`ЛКМ` – клавиатурные сокращения и сокращения кнопок мышки.

  • *Зеркало (Mirror)* – метки интерфейса.

  • :menuselection:`3D-Вьюпорт --> Добавить --> Меш --> Обезьяна` – меню.

Примеры кода

Для языков программирования предоставляется подсветка синтаксиса, а также необязательный показ номеров строк, включаемый параметром :linenos::

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Изображения

Для размещения изображения следует использовать рисунки:

.. figure:: /images/interface_window-system_splash_current.png

   Image caption.

Для единообразия, и поскольку было бы хорошо обеспечить, чтобы все скриншоты были одинакового размера при размещении рядом с текстом, авторы должны делать скриншоты следующим образом:

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

  2. Увеличьте масштаб до максимального уровня (удерживайте NumpadPlus или Ctrl-СКМ или аналогичную).

  3. Уменьшите масштаб на восемь уровней (NumpadMinus – восемь раз).

  4. В некоторых случаях вы пожелаете оставить небольшой запас вокруг объекта, который вы пытаетесь запечатлеть. Это должно быть около 30 пикселей, не обязательно идеально точно.

Это можно применить к нескольким частям интерфейса, но может работать не во всех случаях.

Файлы

Без заглавных и пробельных символов

Имена файлов должны быть в нижнем регистре, слова в имени должны разделяться символами подчёркивания.

Практичная сортировка

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

Формат (format)

Используйте формат .png для изображений, содержащих малое количество цветов, например, для скриншотов интерфейса Blender, а формат .jpg для изображений с большим количеством различных цветов, например, для примеров визуализации (sample renders) и фотографий.

Не используйте анимированные файлы .gif, их сложно поддерживать, они могут отвлекать и обычно имеют большой размер. Вместо этого используйте видео, если это необходимо (см. Видео ниже).

Положение (location)

Помещайте изображения в каталог manual/images. Не используйте другие подкаталоги.

Именование

Для именования файлов используйте подчеркивание для разделения глав и разделов и тире для разделения разделов, состоящих из двух или более слов. Таким образом, файлы изображений должны выглядеть так: глава_подраздел_подподраздел_идентификатор.png, например:

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

Не используйте специальные символы или пробелы!

Руководства по использованию

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

  • Когда документируете панель или раздел пользовательского интерфейса, лучше использовать одно изображение, показывающее все затрагиваемые области (вместо использования нескольких изображений для каждой иконки или кнопки). Изображение лучше поместить сверху раздела, который его описывает, и объяснять возможности в том порядке, в котором они появляются на изображении.

    Примечание

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

Видео

Видео можно встроить из собственного экземпляра PeerTube Blender, который можно найти по адресу video.blender.org. Чтобы встроить видео, используйте следующую директиву:

.. peertube:: ID

Параметр ID находится в адресе видео, то есть:

ID для https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c является 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

Чтобы загрузить новое видео, обратитесь к Администратору проекта документации или включите загруженное видео в описание своего запроса на включение.

Руководства по использованию

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

  • Не вставляйте видеоуроки как средство объяснения какой-либо функции, само описание должно адекватно её объяснять. (Хотя вы можете разместить ссылку на видео внизу страницы под заголовком Учебные пособия (Tutorials)).

Полезные конструкции

  • |BLENDER_VERSION| – вычисляется в текущую версию Blender.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` – аббревиатуры отображают свой полный текст во всплывающей подсказке.

  • :term:`Неразвёртываемый <manifold>` – ссылки на записи в словаре терминов.

Перекрёстные ссылки и связи

Вы можете сослаться на другой документ в руководстве при помощи следующей конструкции:

:doc:`The Title </section/path/to/file>`

Для ссылки на определённый раздел в другом (либо том же самом) документе доступны определённые метки:

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Ссылки на заголовки в том же файле:

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Ссылки во внешний мир:

`Blender Website <https://www.blender.org>`__

Контекстно-зависимый доступ к руководству

В Blender можно создать ссылку на определённую часть руководства, открыв контекстное меню (щёлкнув правой кнопкой мышки) свойства (property) или оператора и выбрав Онлайн-руководство. Чтобы это работало, это должно быть учтено в документации. Чтобы связать свойство или оператор с определенной частью руководства, вам необходимо добавить тег внешней ссылки, идентификатор (ID) которого соответствует тегу RNA Blender’а. Самый простой способ узнать, что такое тег для свойства, – открыть контекстное меню свойства/оператора и выбрать Интернет-справочник по Python, чтобы извлечь тег из URL-адреса. Некоторые примеры того, как это выглядит в документе RST, приведены ниже:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

Для оператора:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Icons

Blender’s icons can be included as inline text using:

`:bl-icon:`<icon_name>`

Дальнейшее чтение

Чтобы узнать больше о reStructuredText, смотрите следующие ссылки:

Sphinx RST Primer

Хорошее базовое введение.

Docutils reStructuredText Reference

Ссылки на справочное руководство и пользовательскую документацию.