Путівник зі Стилю Розмітки – Markup Style Guide

Ця сторінка охоплює умовності щодо написання та використання синтаксису розмітки reStructuredText (RST).

Умовності – Conventions

Відступ у три пробіли.
Рядки повинні мати довжину, меншу за 120 символів.
Для імен кнопок/меню використовується курсив.

Інші вільні умовності:

Уникайте символів Unicode.
Уникайте важко переносного тексту (тобто, речень, що складаються з кількох рядків).

Заголовки – Headings

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

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

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

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

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

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

Примітка

Parts, частини повинні використовуватися тільки для сторінок змісту або покажчика.

Примітка

Кожен .rst файл повинен мати тільки один заголовок глави (*) на файл.

Стилізація тексту – Text Styling

Дивіться overview on ReStructuredText для отримання додаткової інформації про те, як стилізувати різні елементи документації та як додавати списки, таблиці, картинки та блоки коду. Цей довідник Sphinx reference надає більше розуміння додаткових конструкцій.

Нижче наведено корисні розмітки для стилізації тексту:

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

Елементи інтерфейсу – Interface Elements

:kbd:`LMB` – гарячі сполучення клавіш клавіатури або кнопок миші.
*Mirror* – позначки інтерфейсу.
«3D Оглядвікно > Додання > Сіть > Мавпа» – :menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – меню.

Приклади Коду – Code Samples

Доступна підтримка підсвітки синтаксису, якщо підтримується відповідна мова програмування, а також номери рядків можуть додатково показуватися за допомогою опції :linenos:

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Зображення – Images

Для розміщення ілюстративних зображень повинно використовуватися слово «figure»:

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

   Image caption.

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

Підготуйте область, яку ви хотіли б захопити, переконавшись, що використовуєте стандартні тему та устави. (У деяких випадках вам може бути не бажано використовувати стандартні устави, наприклад, якщо деякі опції сховані за стягом.)
Присуньте вигляд на максимальний рівень зуму (утримуйте NumpadPlus або Ctrl-MMB чи подібне).
Відсуньте вигляд на вісім рівнів зуму (NumpadMinus – вісім раз)
У деяких випадках вам бажано буде залишити невеликий припуск навколо речі, яку ви намагаєтеся захопити. Це має бути близько 30 пікселів, але не обов’язково має бути точно так.

Це може застосовуватися до різних частин інтерфейсу, але може не працювати для усіх випадків.

Файли – Files

Ніяких Заголовних, ніяких пробілів – No Caps, No Gaps

Імена файлів мають бути рядковими літерами у нижньому регістрі та зв’язані символом підкреслення між словами.

Сортувати корисно – Sort Usefully

Порядок іменування визначається специфічними ідентифікаторами на кінцях імен.

Формат – Format

Використовуйте .png для зображень, що мають чисті кольори, зокрема, для екранознімків інтерфейсу Blender’а, та .jpg для зображень з великою кількістю колірних варіацій, таких як зразки рендерів та фотографії.

Не використовуйте анімовані файли .gif, їх важко підтримувати, вони можуть відволікати та зазвичай мають великий файловий розмір. Натомість при необхідності використовуйте відео (дивіться Videos нижче).

Локація – Location

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

Іменування – Naming

Для іменування файлів використовуйте підкреслення для відокремлення глав та розділів, а також використовуйте тире для відокремлення розділів, назви яких складаються з двох або більше слів. Отже, для файлів зображень це повинно виглядати так: chapter_subsection_sub-subsection_id.png, наприклад:

interface_splash_current.png
interface_undo-redo_last.png
interface_undo-redo_repeat-history-menu.png

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

Настанови щодо використання – Usage Guides

Уникайте вказування роздільної здатності зображення, щоб тема могла обробляти зображення узгоджено та забезпечувати найкращу розставу на різних розмірах екрану.
При описі панелі або частини Інтерфейсу Користувача краще використовувати єдине зображення, що показує усі відповідні області (а не кілька зображень для кожної іконки чи кнопки), та розміщувати його на початку підрозділу тексту, а потім пояснювати функції цієї ділянки інтерфейсу за порядком проглядання їх на цьому зображенні.

Примітка

Важливо, щоб цей посібник міг підтримуватися тривалий час, інтерфейс користувача та опції засобів змінюються, тому намагайтеся уникати наявності великої кількості зображень (коли вони не є особливо необхідними). Інакше, це стає надто великим навантаженням для підтримування.

Відео – Videos

Відео можуть вбудовуватися з примірника PeerTube для Blender, який можна знайти на video.blender.org. Для вбудовування відео використовуйте наступну директиву:

.. peertube:: ID

Ідентифікатор ID знаходиться в URL відео, наприклад:

Ідентифікатор ID для https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c є 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

Для вивантаження нового відео сконтактуйтеся з Documentation Project Administrator або включіть вивантажуване відео в опис вашої латки Patch.

Настанови щодо використання – Usage Guides

Уникайте додавання відео, що спираються на голос чи слова, оскільки це важко перекладати.
Не вставляйте відеонавчальники як засіб пояснення функцій, написання саме повинно пояснювати їх достатньо. (Хоча можете включати посилання на потрібне відео внизу сторінки під заголовком Tutorials).

Useful Constructs – Корисні Конструкції

|BLENDER_VERSION| – Перетворюється у номер поточної версії Blender.
:abbr:`SSAO (Screen Space Ambient Occlusion)` – Абревіатури показують повний текст при наведенні миші у вигляді підказки для читача.
:term:`Manifold` – Посилання на запис у Глосарії – Glossary.

Перехресні посилання та взаємопосилання – Cross References and Linkage

Ви можете посилатися на інший документ у цьому довіднику за допомогою:

: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

Можливо пов’язати певну частину підручника з Blender шляхом відкриття контекстного меню (клацання правою кнопкою миші) на властивості або операторів та вибрання Online Manual. Щоб це працювало, це необхідно враховувати в документації. Для пов’язання властивості чи оператора з певною частиною посібника вам необхідно додати зовнішній тег орієнтирного посилання, чий ідентифікатор ID відповідає тегу RNA в Blender’і. Найлегший спосіб дізнатися, яким є тег для властивості, – відкрити контекстне меню властивості/операторі та вибрати Online Python Reference – «Онлайнова Довідка з 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
=========

Додаткові Матеріали – Further Reading

Щоб дізнатися більше про reStructuredText, дивіться:

Sphinx RST Primer: Хороший базовий вступ.
Docutils reStructuredText Reference: Посилання на орієнтири та користувацьку документацію.