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

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

Соглашения

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

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

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

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

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

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

Заголовки

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

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

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

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

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

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

Примечание

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

Примечание

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

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

See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.

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

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

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

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

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

  • :menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – menus.

Примеры кода

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Изображения

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

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

   Image caption.

For consistency, and since it would be good to ensure screenshots are all a similar size when floated next to text, writers should take screenshots in the following manner:

  1. Prepare the area you would like to capture making sure to use the default theme and setting. (In some cases you may not want to use the default settings e.g. if some options are hidden behind a checkbox.)

  2. Zoom to the maximum zoom level (hold NumpadPlus or Ctrl-MMB or similar).

  3. Zoom out eight zoom levels (NumpadMinus – eight times).

  4. In some cases you will want to leave a small margin around the thing you are trying to capture. This should be around 30px but does not have to be exact.

This can be applied to several parts of the interface but might not work for all cases.

Файлы

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

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

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

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

Формат

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

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

Расположение

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

Именование

For naming files use underscores to separate chapters and sections, and use dashes to separate sections that are two or more words. So for image files should look like: chapter_subsection_sub-subsection_id.png, e.g:

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

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

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

  • Avoid specifying the resolution of the image, so that the theme can handle the images consistently and provide the best layout across different screen sizes.

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

    Примечание

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

Видео

Videos can be embedded from Blender’s self-hosted PeerTube instance which can be found at video.blender.org. To embed a video using the following directive:

.. peertube:: ID

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

The ID for https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c is 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

To get a new video uploaded, contact a Documentation Project Administrator or include the uploaded video in your Pull Request description.

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

  • Avoid adding videos that rely on voice or words, as this is difficult to translate.

  • Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately. (Though you may include a link to the video at the bottom of the page under the heading Tutorials).

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

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

  • :abbr:`SSAO (Screen Space Ambient Occlusion – 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>`__

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by opening the context menu (right click) of a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to open the context menu of the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

.. _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...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

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

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

Sphinx RST Primer

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

Docutils reStructuredText Reference

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