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

Эта страница покрывает соглашения по написанию и использованию разметки 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-вид --> Добавить --> Полисетка --> Обезьяна` – меню.

Примеры кода

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Изображения

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

.. figure:: /images/render_cycles_nodes_types_shaders_node.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.

Файлы

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

Use .png for images that have solid colors such as screenshots of the Blender interface, and .jpg for images with a high amount of color variance, such as sample renders and photographs.

Do not use animated .gif files, these are hard to maintain, can be distracting and are usually large in file size. Instead use a video if needed (see Videos below).

Расположение
Помещайте изображения в каталог 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

Do not use special characters or spaces!

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

  • 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 from YouTube™ and Vimeo™ can be embedded using:

.. youtube:: ID

.. vimeo:: ID

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

  • ID для видео https://www.youtube.com/watch?v=Ge2Kwy5EGE0 - Ge2Kwy5EGE0
  • ID для видео https://vimeo.com/15837189 - 15837189

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

  • Избегайте добавления видео, которое сильно зависит от голоса, поскольку его значительно сложнее переводить.
  • Не внедряйте видеоуроки для описания какой-либо функции, её описание должно адекватно её объяснять (но вы можете включить ссылку на видео внизу страницы под заголовком 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>`__

Directory Layout

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

  • название_каталога/
    • index.rst (содержит ссылки на внутренние файлы)
    • introduction.rst
    • раздел_1.rst
    • раздел_2.rst

Например:

  • rendering/
    • index.rst
    • cycles/
      • index.rst
      • introduction.rst
      • materials/
        • index.rst
        • introduction.rst
        • volumes.rst

Идея заключается в том, чтобы заключить всё содержимое раздела внутри каталога. В идеале каждый раздел должен иметь файлы index.rst (содержащий оглавление данного раздела) и introduction.rst (введение к содержанию раздела).

Содержание

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

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

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

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

Пример Sphinx RST
Хорошее базовое введение.
Справка по reStructuredText
Ссылки на справочное руководство и пользовательскую документацию.