Перейти до змісту

Керівництво зі стилю оформлення документації

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

Загальний стиль

  • У заголовках і назвах великою літерою слід писати лише перше слово.
  • Ми віддаємо перевагу американській орфографії, допускаючи певні відхилення у вигляді розмовних виразів, характерних для сфери програмування (наприклад, «apps»), та перетворення іменників на дієслова (наприклад, «scrollable»).
  • Написання слів «artefact» та «artefacts» відповідає наведеному прикладу.
  • Після крапки ми ставимо один пробіл.
  • В якості довгих тире ми використовуємо один дефіс, оточений пробілами (або HTML-літерал —).
  • У будь-якому згадуванні назви продукту слід дотримуватися рекомендованого способу написання з великої літери. (Наприклад, «macOS», «GTK», «pytest», «Pygame», «PyScript»).
  • Якщо термін використовується «як код», його слід наводити у вигляді вбудованого коду, взявши його в одинарні зворотні лапки, а не додавати до словника.
  • Ми уникаємо використання таких слів, як «просто», «лише» або «легко», описуючи дії, які повинен виконати користувач. Ці слова можуть сприйматися як зневажливі, особливо коли користувач стикається з труднощами.

Перехресні посилання на інформацію

Слід, по можливості, вказувати перехресні посилання на вміст у документації. У цьому розділі розглядаються різні способи, як це можна зробити, кожен із яких залежить від типу інформації, на яку робиться посилання.

MkDocs відображає посилання, відформатовані за стандартом Markdown. Веб-гіперпосилання, відформатовані за стандартом Markdown, мають такий вигляд:

[Текст посилання](https://example.com/)

Ви також можете використовувати цей формат для створення посилання на локальний файл:

[Текст посилання](шлях/до/файлу.md)

Для посилання на конкретні розділи файлів або документацію API необхідно використовувати формат посилань MkDocs.

Налаштовані анкори Markdown та перехресні посилання на вміст

Markdown генерує анкори для всіх заголовків (будь-якого тексту в одному рядку, що починається з одного до шести символів #), виходячи з вмісту заголовка. Наприклад, анкор, згенерований для цього розділу, — custom-markdown-anchors-and-content-cross---referencing. Однак через особливості роботи наших перекладів, щоразу, коли згадується заголовок розділу, він повинен мати власне посилання.

MkDocs підтримує відображення синтаксису посилань на елементи, що дозволяє створювати посилання на різні інші елементи в документації за допомогою модифікованого посилання Markdown. Це, зокрема, включає створення посилань на користувацькі заголовки Markdown та текстові анкори.

Посилання на довідку MkDocs — це будь-які посилання, оформлені у такому вигляді:

[Текст посилання][адреса посилання]

Необхідно вказати власні анкори заголовка та вмісту

Будь-який заголовок або розділ вмісту, на який у текстовому вмісті посилається посилання MkDocs у документації BeeWare, повинен мати прив’язану власну прив’язку. В іншому разі існує ризик, що посилання перестануть працювати під час перекладу вмісту заголовка.

Якщо вам потрібно створити посилання на анкор у заголовку, вам доведеться створити власний анкор для відповідного вмісту. Загальний синтаксис для встановлення власного анкора такий:

# Текст заголовка { #anchor-name }

Наприклад, щоб налаштувати анкор для цього розділу на custom-anchors, слід застосувати таке форматування:

## Налаштовані анкори Markdown { #custom-anchors }

Ви також можете створити анкор на загальному вмісті, зокрема на тексті та блоках коду. Над вмістом, на який ви хочете встановити посилання, слід розмістити такий формат із символами нового рядка зверху та знизу:

Вміст вище.

[](){ #anchor-name }

Вміст нижче, який тепер прив’язаний до анкора вище.

Після створення власних анкорів ви можете розміщувати посилання на них як у цьому ж документі, так і в інших частинах документації.

Стандартний Markdown використовується для створення посилань на анкор у тому самому файлі, що оформляється наступним чином:

[Текст посилання](#anchor-name)

Для створення посилання на анкор у окремому документі використовується стиль посилання MkDocs, який має такий вигляд:

[Текст посилання][назва анкора]

Посилання на довідку щодо API

Функція посилань у довідці MkDocs також підтримує перехресні посилання на документацію API, зокрема на описані класи, методи класів або атрибути, а також на конкретні зовнішні джерела документації.

Існує кілька способів посилання на задокументований клас, метод класу або атрибут, незалежно від того, чи ви посилаєтеся з того самого файлу, чи з окремого. При посиланнях на класи тощо необхідно вказувати зворотні лапки в першій парі квадратних дужок, щоб ім’я відображалося як вбудований код. Обернені лапки не потрібні лише в тому випадку, якщо ви використовуєте власний текст, який не повинен відображатися як вбудований код. Обернені лапки ніколи не слід вказувати у другій парі квадратних дужок.

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

[`module.ClassName`][]

Посилання на клас, при якому відображається лише назва класу, оформлюється наступним чином:

[`ClassName`][module.ClassName]

Атрибути такі самі, як зазначено вище, з урахуванням назви атрибута. Нижче наведено простір імен:

[`module.ClassName.attributename`][]

Як і у випадку з класами, відображення лише імені атрибута оформлюється наступним чином:

[`attributename`][module.ClassName.attributename]

Методи слід вказувати з () після простору імен, тому до них слід застосовувати інший підхід, ніж до атрибутів. Нижче наведено правильний спосіб посилання на метод:

[`module.ClassName.methodname()`][module.ClassName.methodname]

У наведеному нижче прикладі відображаються лише назви класів та методів. Для цього також потрібно додати дужки після назви:

[`Classname.methodname()`][module.Classname.methodname]

Ви можете створити посилання на клас, метод або атрибут, одночасно відображаючи довільний текст, використовуючи той самий метод із відповідним простором імен. У випадку з класом це оформлюється наступним чином:

[текст посилання][module.ClassName]

Також можна створювати прямі посилання на документацію до ядра Python, а також на документацію до Pillow. Наприклад, щоб створити посилання на документацію щодо int:

[`int`][]

Щоб перейти за посиланням на документацію до Pillow Image:

[`PIL.Image.Image`][]

Поради щодо блоків коду

Підсвічування тексту та коду

Ви можете вказати мову коду, що міститься в блоці коду, вказавши назву мови після перших трьох зворотних лапок без пробілу між ними. Це забезпечить правильне підсвічування коду під час його відображення. Наприклад, щоб вказати Python, потрібно почати блок коду з ```python.

Команди консолі та кнопка копіювання

Якщо ви вставляєте консольні команди або команди з виведенням, позначте їх як console або doscon, залежно від того, чи описуєте ви Unix-подібну операційну систему (включно з macOS), чи Windows. Ви можете включити командний рядок, що надається операційною системою; при натисканні кнопки «Копіювати» буде скопійовано лише саму команду. Наприклад, якщо ви починаєте блок коду з ```console, і включаєте такий вміст:

$ mkdir test
$ ls
test

У такому разі натискання кнопки «Копіювати» у блоці коду призведе до копіювання лише команд, а підказки та результати виконання будуть проігноровані. Це дозволяє вказати, що це консольні команди, і водночас дає користувачам можливість ефективно використовувати кнопку «Копіювати».

Виділення окремих рядків коду

Ви можете виділити певні рядки коду. Наприклад, щоб виділити рядок 2, потрібно додати пробіл після назви мови, а потім — {hl_lines="2"}. Отже, ваш блок коду має починатися з ```python {hl_lines="2"}. У результаті ви отримаєте:

import toga
from toga.style.pack import COLUMN, ROW

Ви можете виділити кілька різних рядків. Наприклад, python {hl_lines="3 5 9"} виділить рядки 3, 5 і 9. Ви також можете виділити діапазон рядків. Наприклад, python {hl_lines="3-8"} виділить рядки з 3 по 8. Ви можете виділити кілька діапазонів, наприклад, за допомогою python {hl_lines="9-18 23-44"}.

Елементи Markdown, що вимагають особливого форматування

З огляду на спосіб формування файлів перекладу важливо в синтаксисі Markdown вказувати необхідні символи перенесення рядка для застережень, приміток, вкладок, директив Jinja, підписів до зображень та вирівнювання тощо.

Поради та примітки

Попередження повинні бути оформлені наступним чином, причому перед початком і після закінчення попередження має бути новий рядок:

Текст вище.

/// застереження | Заголовок

Текст застереження.

Другий абзац.

///

Текст нижче.

Це працює так само з будь-яким підтримуваним типом зауваження. Наприклад, зауваження-примітки вимагають такого самого форматування та розривів рядків:

Вміст вище.

/// примітка | Заголовок примітки

Текст примітки тут.

///

Вміст нижче.

Усі підтримувані типи зауважень можна використовувати як зауваження.

Вміст у вкладках

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

Вміст вище.

/// вкладка | Заголовок першої вкладки

Текст першої вкладки

///

/// вкладка | Заголовок другої вкладки

Текст другої вкладки.

///

/// вкладка | Заголовок третьої вкладки

Текст третьої вкладки.

///

Вміст нижче.

Вкладка з вкладеним застереженням буде оформлена наступним чином, із символом нового рядка перед і після блоку вмісту:

Вміст вище.

/// вкладка | Windows

Текст вкладки.

/// застереження | Застереження

Текст застереження.

///

///

Вміст нижче.

Згорнутий вміст

Схований вміст оформлено таким чином, включаючи символи перенесення рядка:

Вміст вище.

/// details-note | Заголовок згорнутого вмісту

Згорнутий вміст.

///

Вміст нижче.

Усі підтримувані типи попереджень можна використовувати зі згорнутим вмістом, однак їх необхідно вказувати у вигляді details-admonitiontype. Отже, згорнутий блок типу «примітка» матиме вигляд details-note (як показано вище), згорнутий блок типу «попередження» — details-warning і так далі.

Вказівки щодо дзіндзя

У деяких розділах документації в тексті використовуються директиви Jinja. Усе, що використовує функції директив Jinja, має бути оточене символами нового рядка. Наприклад, у підручнику BeeWare містяться умовні оператори Jinja, що базуються на змінних і визначають, яке попередження відображати на головній сторінці. Вони оформлюються наступним чином:

Вміст вище.



Вміст нижче.

Також існує синтаксис для заміни символів або тексту. Цей синтаксис являє собою змінну, укладену в пару відповідних подвійних фігурних дужок, і, якщо вона розташована в окремому рядку, повинна містити символ перенесення рядка як перед, так і після неї.

Вміст вище.

{{ variable }}

Вміст нижче.

Форматування зображень

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

Встановлення ширини 300px для зображення буде оформлено наступним чином:

![Альтернативний текст зображення](../шлях/до/зображення.png){ width="300px" }

Вирівнювання зображення ліворуч (або праворуч) оформляється наступним чином:

![Альтернативний текст зображення](../шлях/до/зображення.png){ align=left }

Щоб додати підпис до зображення, перед ним і після нього потрібно поставити символ нового рядка; підпис оформлюється наступним чином:

Текст вище.

![Альтернативний текст зображення](/path/to/image.png)

/// підпис

Текст підпису.

///

Текст нижче.

Вирівняти зображення по центру за допомогою атрибута align неможливо. Щоб обійти цю проблему, слід додати після зображення порожній підпис — тоді воно буде вирівняне по центру. Між кожним розділом, а також перед і після нього необхідно вставляти символи нового рядка. Форматування виглядає так:

Текст вище.

![Альтернативний текст зображення](../path/to/image.png)

/// підпис

///

Текст нижче.

Плагіни з певним форматуванням Markdown

У наступних розділах розглядається, як використовувати плагіни, що вимагають певного форматування у форматі Markdown.

Використання фрагментів для вставлення зовнішнього вмісту

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

Важливі зауваження:

  • Ми використовуємо -8<- як ідентифікатор фрагментів коду. У документації наведено кілька варіантів; будь ласка, дотримуйтесь нашого стилю.
  • Файли, що містяться у спільній папці BeeWare Docs Tools, розглядаються як «локальний» вміст. Тому вам слід використовувати або лише ім’я файлу, як у -8<- "docs-style-guide.md", або, якщо вміст знаходиться у підкаталозі, лише ім’я каталогу та ім’я файлу, як у -8<- "style/docs-style-guide.md".
  • Якщо ви вставляєте зовнішній вміст із файлу на GitHub за допомогою URL-адреси, ви обов’язково повинні використовувати URL-адресу «сирого» вмісту, інакше у місці вставки буде відображатися вся веб-сторінка.

Використання макросів для вставлення вмісту зі спільних ресурсів BeeWare Docs Tools

Ви також можете включити вміст із каталогу спільного доступу інструментів BeeWare Docs за допомогою плагіна Macros MkDocs. Цей метод необхідний, якщо документ містить директиви Jinja, які потрібно виконати, і його слід використовувати лише в цій ситуації. Він не працюватиме із зовнішнім вмістом, на який посилається URL-адреса. З цим методом сумісний механізм заміни змінних Macros.

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

  1. Використовуйте синтаксис Jinja include, якщо ви хочете включити документ без внесення до нього будь-яких інших змін вручну.

  2. Використовуйте синтаксис Jinja extends, якщо ви включили синтаксис Jinja block у документ; це дозволить вам замінити або доповнити певні розділи.

pyspelling

Ми використовуємо програму перевірки орфографії pyspelling. Вона запускається під час перевірок на наявність помилок.

Коли pyspelling виявляє слово з орфографічною помилкою, у більшості випадків його слід виправити в тексті документації.

У тому рідкісному випадку, якщо система виявить правильне слово, якого немає у словнику pyspelling, у вас є два варіанти:

  1. Якщо це слово, яке, ймовірно, буде використовуватися багато разів, його слід додати до документа spelling_wordlist у каталозі docs, розмістивши в алфавітному порядку.
  2. Якщо це слово, яке, ймовірно, більше не буде використовуватися, його можна взяти в теги <nospell> / </nospell>, і pyspelling проігнорує його в тексті.