Путівник зі Стилю Розмітки – 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

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``

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

  • :kbd:`LMB` – гарячі сполучення клавіш клавіатури або кнопок миші.

  • *Mirror* – позначки інтерфейсу.

  • «3D Оглядвікно > Додання > Сіть > Мавпа» – :menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – меню.

Operator Menus

Each operator should receive its own heading or page based on the length of the content. Each operator should have a reference admonition documenting the context of the operator:

.. admonition:: Reference
   :class: refbox

   :Mode:      Edit Mode
   :Menu:      :menuselection:`Curve --> Snap`
   :Hotkey:    :kbd:`Shift-S`

Panels

Panels should be documented by their own heading, nested panels should use decreasing heading levels. Each panel could have its own page based on the length of documentation and/or the amount of panels. Expanded menus that toggle what properties are presented to the user should be treated like subpanels:

Panel Title
===========

Nested Panel Title
------------------

Properties

Properties should be documented using definition lists. Properties that are hidden based on other properties should used nested definitions:

Property
   Property description.

   Hidden Property
      Hidden property description.

Enum based menus should be documented using the following syntax:

Menu Label
   General description of the menu.

   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by right clicking on 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 right click on 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
=========

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

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

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

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

.. figure:: /images/interface_splash_current.png

   Image caption.

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

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

  2. Присуньте вигляд на максимальний рівень зумування (утримуйте NumpadPlus або Ctrl-MMB чи подібне).

  3. Відсуньте вигляд на вісім рівнів зумування (NumpadMinus – вісім раз)

  4. У деяких випадках вам бажано залишити невелике поле навколо елемента, який намагаєтеся захопити. Воно повинно бути за величиною біля 30px, але це не обов’язково має бути точно.

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

Файли – 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

Videos from YouTube™ can be embedded using:

.. youtube:: ID

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

The ID for https://www.youtube.com/watch?v=Ge2Kwy5EGE0 is Ge2Kwy5EGE0.

Настанови щодо використання – 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>`__

Розстава Каталогів – Directory Layout

Підрозділи повинні у загальному бути структуровані так:

  • directory_name/

    • index.rst (містить посилання на внутрішні файли)

    • introduction.rst

    • section_1.rst

    • section_2.rst

Наприклад:

  • rendering/

    • index.rst

    • cycles/

      • index.rst

      • introduction.rst

      • materials/

        • index.rst

        • introduction.rst

        • volumes.rst

Ідея тут полягає у тому, щоб розмістити увесь вміст підрозділу всередині однієї теки. В ідеалі кожен підрозділ повинен мати index.rst (що містить зміст для цієї секції) та introduction.rst (вступ) у вміст цієї секції.

Зміст – Table of Contents

Стандартно, зміст повинен показувати два рівні глибини:

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

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

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

Sphinx RST Primer

Хороший базовий вступ.

Docutils reStructuredText Reference

Посилання на орієнтири та користувацьку документацію.