Перейти к содержанию

Руководство по стилю документации

Это руководство содержит информацию об ожидаемом стиле, синтаксисе MkDocs, различных необходимых инструментах и переводе документации, касающейся написания нового контента и перевода существующего контента.

Общий стиль

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

Ссылочная информация

По возможности следует делать перекрестные ссылки на контент в документации. В этом разделе описаны различные способы, каждый из которых зависит от типа информации, на которую делается ссылка.

MkDocs отображает стандартные ссылки в формате Markdown. Стандартные веб-гиперссылки в формате Markdown выглядят следующим образом:

[Link text](https://example.com/)

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

[Link text](path/to/file.md)

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

Пользовательские анкоры Markdown и перекрестные ссылки на контент

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

MkDocs поддерживает рендеринг синтаксиса ссылочных ссылок, который позволяет вам создавать ссылки на различные другие элементы в документации с помощью модифицированной ссылки Markdown. Это включает в себя, среди прочего, ссылки на пользовательские заголовки Markdown и текстовые анкоры.

Ссылки MkDocs — это любые ссылки, оформленные следующим образом:

[Link text][link-target]

Требуются пользовательские заголовки и контентные анкоры

Любой заголовок или раздел содержания, на который есть ссылка в текстовом содержании через ссылку MkDocs в документации BeeWare, должен иметь прикрепленную пользовательскую анкорную ссылку. В противном случае существует вероятность, что ссылки будут нарушены при переводе содержания заголовка.

Если вам нужно создать ссылку на заголовок, вам необходимо сгенерировать пользовательскую ссылку для нужного контента. Общий синтаксис для установки пользовательской ссылки следующий:

# Header text { #anchor-name }

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

## Custom Markdown anchors { #custom-anchors }

Вы также можете создать анкор на общем контенте, включая текст и блоки кода. Следующее форматирование с новыми строками выше и ниже должно быть включено над контентом, на который вы хотите сослаться:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

После создания пользовательских якорей вы можете создавать ссылки на них из того же документа или из других частей документации.

Стандартный Markdown используется для ссылки на анкор в том же файле, который форматируется следующим образом:

[Link text](#anchor-name)

Ссылка на анкор в отдельном документе использует стиль ссылки MkDocs, который форматируется следующим образом:

[Link text][anchor-name]

Ссылки на справочник 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]

Вы можете создать ссылку на класс, метод или атрибут, отображая произвольный текст, используя тот же метод с применимым пространством имен. Для класса это оформляется следующим образом:

[link text][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 для предупреждений, примечаний, вкладок, директив Jinja, подписей к изображениям, выравнивания и т. д.

Предупреждения и заметки

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

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Это работает одинаково с любым поддерживаемым типом предупреждения. Например, предупреждения в примечаниях требуют того же форматирования и новых строк:

Content above.

/// note | Note title

Note text here.

///

Content below.

Все поддерживаемые типы предупреждений доступны для использования в качестве предупреждений.

Вкладки с контентом

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

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

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

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Свернутое содержимое

Свернутый контент форматируется следующим образом, включая новые строки:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Все поддерживаемые типы предупреждений доступны для использования со свернутым контентом, однако вы должны объявить их как details-admonitiontype. Таким образом, свернутый блок типа «примечание» будет details-note (как показано выше), свернутый блок типа «предупреждение» будет details-warning, и так далее.

Директивы Jinja

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

Content above.



Content below.

Существует также синтаксис для замены символов или текста. Этот синтаксис представляет собой переменную, заключенную в пару соответствующих двойных фигурных скобок, и, если она находится в отдельной строке, должна содержать символ новой строки до и после нее.

Content above.

{{ variable }}

Content below.

Форматирование изображений

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

Установка ширины 300px для изображения будет оформлена следующим образом:

![Image alt text](../path/to/image.png){ width="300px" }

Выравнивание изображения по левому (или правому) краю будет оформлено следующим образом:

![Image alt text](../path/to/image.png){ align=left }

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

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

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

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Плагины с определенным форматированием Markdown

В следующих разделах описано, как использовать плагины, требующие специального форматирования Markdown.

Использование фрагментов для включения внешнего контента

Подробные сведения о том, как включить внешний контент из локального файла или URL-адреса, см. в документации по расширению Snippets. Фрагменты следует использовать, если документ не содержит директив Jinja, которые необходимо выполнить (выполнение Jinja происходит одновременно с обработкой фрагментов, поэтому любые директивы 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. Используйте синтаксис extends Jinja, если вы включили синтаксис Jinja block в документ, что позволяет вам переопределять или добавлять определенные разделы.

pyspelling

Мы используем программу проверки орфографии pyspelling. Она запускается во время проверки lint.

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

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

  1. Если это слово, которое, вероятно, будет использоваться несколько раз, вам следует добавить его в документ spelling_wordlist в каталоге docs в алфавитном порядке.
  2. Если это слово вряд ли будет использоваться снова, вы можете обернуть его тегом <nospell> / </nospell>, и pyspelling проигнорирует его в строке.