Путівник зі стилю розмітки – 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 ReStructured Text про те, як використовувати різні стилі для різних елементів документації та як додавати списки, таблиці, картинки та блоки коду. Орієнтир зі Sphinx reference надає більш глибокі додаткові конструкції для оформлення.

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

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

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

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

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

  • :menuselection:`3D View --> Add --> Mesh --> Monkey` – меню.

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

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

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

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

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

Відео з YouTube™ та Vimeo™ можуть бути вставлені так:

.. youtube:: ID

.. vimeo:: ID

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

  • Ідентифікатор ID для https://www.youtube.com/watch?v=Ge2Kwy5EGE0 — це Ge2Kwy5EGE0

  • Ідентифікатор ID для https://vimeo.com/15837189 — це 15837189

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

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