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.

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

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

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

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

  4. У деяких випадках вам бажано буде залишити невеликий припуск навколо речі, яку ви намагаєтеся захопити. Це має бути близько 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.

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

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

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