Это многостраничный печатный вид этого раздела. Нажмите что бы печатать.

Вернуться к обычному просмотру страницы.

Обзор оформления документации

Темы в этом разделе содержат рекомендации по написанию, форматированию и организации контента, а также охватывают настройку Hugo в контексте документации Kubernetes.

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

На этой странице вы найдёте рекомендации по оформлению написания документации Kubernetes. Это рекомендации, а не правила. Используйте здравый смысл и не стесняйтесь предлагать изменения в этот документ в виде пулреквеста.

Для получения подробной информации о создании нового контента в документацию Kubernetes посмотрите руководство по контенту документации, а также следуйте инструкциям по использованию шаблонов страниц и открытию пулревеста в документацию.

Язык

Документация Kubernetes была переведена на несколько языков (см. README-файлы локализаций).

Процесс локализации документации на другие языки описан в соответствующей странице по локализации.

Правила форматирования документации

Используйте верблюжью нотацию для написания объектов API

Когда вы указываете имя API-объекта, используйте те же самые прописные и строчные буквы так, как они записаны в имени объекта. Как правило, имена объектов API написаны с использованием верблюжьей нотации.

Не разделяйте имя объекта API на отдельные слова. Например, пишите PodTemplateList, а не Pod Template List.

Указывая имена API-объектов, не добавляйте к ним слово "объект", за исключением случаев, когда это только ухудшает читаемость.

Можно делать и нельзя - Объекты API
Можно Нельзя
В Pod два контейнера. В поде два контейнера.
Deployment отвечает за ... Объект Deployment отвечает за ...
PodList — это список Pod. Pod List — это список подов.
Два ContainerPorts ... Два объекта ContainerPort ...
Два объекта ContainerStateTerminated ... Два ContainerStateTerminated ...

Используйте угловые скобки для заполнителей

Используйте угловые скобки для заполнителей. Сообщите читателю, что означает заполнитель.

  1. Отобразить информацию о Pod:

     kubectl describe pod <pod-name> -n <namespace>
    

    Если пространство имён пода равняется default, вы можете опустить параметр '-n'.

Используйте полужирное начертание для элементов пользовательского интерфейса

Можно делать и нельзя - Элементы интерфейса в полужирном начертании
Можно Нельзя
Нажмите на Fork. Нажмите на "Fork".
Выберите Other. Выберите "Other".

Используйте курсивное начертание для определения или включения новых терминов

Можно делать и нельзя - Используйте курсивное начертание для новых терминов
Можно Нельзя
Кластер — это набор узлов ... "Кластер" — это набор узлов ...
Эти компоненты формируют плоскость управления. Эти компоненты формируют плоскость управления.

Оформляйте как код имена файлов, директории и пути

Можно делать и нельзя - Оформляйте как код имена файлов, директории и пути
Можно Нельзя
Откройте файл envars.yaml. Откройте файл envars.yaml.
Перейдите в директорию /docs/tutorials. Перейдите в директорию /docs/tutorials.
Откройте файл /_data/concepts.yaml file. Откройте файл /_data/concepts.yaml.

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

Можно делать и нельзя - Используйте международные правила для пунктуации внутри кавычек
Можно Нельзя
события записываются с соответствующей "стадией". события записываются с соответствующей "стадией."
Копия называется "fork". Копия называется "fork."

Форматирование с использованием однострочного кода

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

Для однострочного (встроенного) блока кода в HTML-документе используйте тег <code>. В файле Markdown используйте обратную кавычку (`).

Можно делать и нельзя - Use code style for inline code and commands
Можно Нельзя
Команда kubectl run создает Deployment. Команда "kubectl run" создает Deployment.
Для декларативного управления используйте kubectl apply. Для декларативного управления используйте "kubectl apply".
Заключите примеры кода в тройные обратные кавычки. (```) Заключите примеры кода с использованием любого другого синтаксиса.
Используйте одинарные обратные кавычки для выделения встроенного кода. Например, var example = true. Используйте две звездочки (**) или подчёркивание (_) для выделения встроенного кода. Например, var example = true.
Используйте тройные обратные кавычки до и после многострочного блока кода для отдельных блоков кода. Используйте многострочные блоки кода для создания диаграмм, блок-схем или т.д.
Используйте понятные имена переменных с соответствующим контекстом. Используйте имена переменных, такие как 'foo', 'bar' и 'baz', которые не имеют смысла и которым не хватает контекста.
Удаляйте завершающие пробелы в коде. Добавляйте конечные пробелы в код там, где они необходимо, поскольку программа для чтения с экрана также будет зачитывать пробелы.

Имена полей объектов и пространства имён оформляйте как код

Можно делать и нельзя - Имена полей объектов и пространства имён оформляйте как код
Можно Нельзя
Задайте значение для поля replicas в конфигурационном файле. Задайте значение для поля "replicas" в конфигурационном файле.
Значением поля exec является объект ExecAction. Значением поля "exec" является объект ExecAction.
Запустите процесс как Daemonset в пространстве имен kube-system. Запустите процесс как Daemonset в пространстве имен kube-system.

Имена компонентов и командного инструмента оформляйте как код

Можно делать и нельзя - Имена компонентов и командного инструмента оформляйте как код
Можно Нельзя
kubelet сохраняет стабильность узла. kubelet сохраняет стабильность узла.
kubectl обрабатывает поиск и аутентификацию на сервере API. kubectl обрабатывает поиск и аутентификацию на apiserver.
Запустите процесс с использованием сертификата kube-apiserver --client-ca-file=FILENAME. Запустите процесс с использованием сертификата kube-apiserver --client-ca-file=FILENAME.

Начинайте предложение с имени инструмента или компонента

Можно делать и нельзя - Начинайте предложение с имени инструмента или компонента
Можно Нельзя
The kubeadm tool bootstraps and provisions machines in a cluster. kubeadm tool bootstraps and provisions machines in a cluster.
The kube-scheduler is the default scheduler for Kubernetes. kube-scheduler is the default scheduler for Kubernetes.

Используйте общее описание вместо имени компонента

Можно делать и нельзя - Используйте общее описание вместо имени компонента
Можно Нельзя
Сервер Kubernetes API следует спецификации OpenAPI. apiserver следует спецификации OpenAPI.
Агрегированные API-интерфейсы — вспомогательные API-серверы. Агрегированные API-интерфейсы — вспомогательные APIServers.

Cтроковые и целочисленные значения полей пишите в обычном стиле

Для значений полей типа string или integer используйте обычный стиль без кавычек.

Можно делать и нельзя - Cтроковые и целочисленные значения полей пишите в обычном стиле
Можно Нельзя
Задайте значение для поля imagePullPolicy как Always. Задайте значение для поля imagePullPolicy как "Always".
Задайте значение для поля image как nginx:1.8. Задайте значение для поляimage как nginx:1.8.
Задайте значение для поля replicas как 2. Задайте значение для поля replicas как 2.

Форматирование фрагментов кода

Не добавляйте символ приглашения командной строки

Можно делать и нельзя - Не добавляйте символ приглашения командной строки
Можно Нельзя
kubectl get pods $ kubectl get pods

Отделяйте команды от вывода

Убедитесь, что Pod работает на выбранном вами узле:

kubectl get pods --output=wide

Вывод будет примерно таким:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Версионирование примеров Kubernetes

Примеры кода и примеры конфигурации, которые включают информацию о версии, должны согласовываться с относящемуся к нему тексту.

Если информация зависит от версии, необходимо определить версию Kubernetes в секции prerequisites шаблона задачи или шаблона руководства. После сохранения страницы секция prerequisites отобразится в отдельном блоке с заголовком Подготовка к работе.

Для указания версии Kubernetes для страницы задачи или руководства в фронтальную часть файла добавьте поле min-kubernetes-server-version.

Если YAML-пример определён в отдельном файле, поищите и просмотрите темы, которые ссылаются на него. Убедитесь, что темы с подключённым YAML-файлом содержат соответствующую информацию о версии. Если ни одна из тем не использует какой-либо YAML-файл подумайте над тем, чтобы удалить его вместо того, чтобы обновления.

Например, если вы пишете руководство, предназначенное для использования с версией Kubernetes 1.8, фронтальная часть вашего Markdown-файла должен выглядеть примерно так:

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

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

apiVersion: v1 # в более ранних версиях...
kind: Pod
...

Словарь Kubernetes.io

Список специфичных для Kubernetes терминов и слов, которые будут регулярно встречаться по всему сайту.

Словарь Kubernetes.io
Термин Пример использования
Kubernetes Kubernetes всегда должен начинаться с заглавной буквы.
Docker Docker всегда должен начинаться с заглавной буквы.
SIG Docs SIG Docs, а не SIG-DOCS или другие варианты.
On-premises On-premises or On-prem rather than On-premise or other variations.

Макрокоды

Макрокоды Hugo помогают создавать разного рода обращений к читателю. Наша документация поддерживает три разных макрокода для этого: примечание {{< note >}}, предостережение {{< caution >}} и предупреждение {{< warning >}}.

  1. Заключите текст в открывающий и закрывающий макрокод.

  2. Используйте следующий синтаксис для определения стиля:

    {{< note >}}
    Вам не нужно указывать надпись; макрокод автоматически добавит её. (Примечание:, Предостережение:, и т.д.)
    {{< /note >}}
    

Результат:

Примечание

Используйте {{< note >}} для выделения подсказки или части информации, которая может быть полезна для ознакомления.

Например:

{{< note >}}
Вы _также_ можете использовать Markdown внутри этих выносок.
{{< /note >}}

Результат:

Вы можете использовать {{< note >}} в списке:

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

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

   {{< note >}}
   Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел [Распространённые проблемы с шорткодами](#распространённые-проблемы-с-шорткодами).
   {{< /note >}}

1. Третий пункт в списке

1. Четвертый пункт в списке

Результат:

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

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

  3. Третий пункт в списке

  4. Четвертый пункт в списке

Предостережение

Используйте {{< caution >}}, чтобы обратить внимание к важной информации, которая поможет избежать подводных камней.

Например:

{{< caution >}}
Оформление выноски применяется только к строке, следующей после тега выше.
{{< /caution >}}

Результат:

Предупреждение

Используйте {{< warning >}} для обозначения предупреждающей информации или такой, которую чрезвычайно важно соблюдать.

Например:

{{< warning >}}
Острожно.
{{< /warning >}}

Результат:

Распространённые проблемы с шорткодами

Упорядоченные списки

Макрокоды сбросят нумерацию в нумерованных списках, если вы не добавите отступ в четыре пробела перед уведомлением и тегом.

Например:

1. Разогреть духовку до 350˚F

1. Подготовить тесто и вылить её в формочку для выпечки.
   {{< note >}}Для лучшего результата смажьте формочку.{{< /note >}}

1. Выпекать 20-25 minutes или пока тесто не зарумянится.

Результат:

  1. Разогреть духовку до 350˚F

  2. Подготовить тесто и вылить её в формочку для выпечки.

  3. Выпекать 20-25 minutes или пока тесто не зарумянится.

Выражения для вставок

Макрокоды внутри include-выражений нарушит процесс сборки. Поэтому они должны быть вставлены в родительский документ до и после вызова include. Например:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Элементы Markdown

Переносы строк

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

Заголовки

Люди, просматривающие документацию, могут использовать программу чтения с экрана или другую вспомогательную технологию (Assistive technologies, AT). Программы чтения с экрана — устройства вывода, которые выводят элементы на странице по очереди. Если на странице много текста, вы можете использовать заголовки, чтобы придать странице внутреннюю структуру. Хорошая структура страницы помогает всем читателям легко перемещаться по странице или выбрать интересующие темы.

Можно делать и нельзя - Заголовки
Можно Нельзя
Обновите заголовок в фронтальной части страницы или записи блога. Используйте заголовок первого уровня, так как Hugo автоматически преобразует название страницы в фронтальной части в заголовок первого уровня.
Используйте упорядоченные заголовки, чтобы сформировать общее представление о содержании страницы. Используйте заголовки с уровня 4 по 6, если только это только в этом нет необходимости. Если текст настолько подробный, возможно, его нужно разделить на отдельные статьи.
Используйте знак решётки или хеша (#) для всех видов контента, кроме записей блога. Используйте подчеркивание (--- или ===) для обозначения заголовков первого уровня.
Начинайте с большой буквы только первое слово в заголовке. Например, Расширение kubectl с помощью плагинов Пишите с заглавной буквы все слова в заголовке. Например, Расширение Kubectl С Помощью Плагинов

Параграфы

Можно делать и нельзя - Параграфы
Можно Нельзя
Проследите за тем, чтобы в одном абзаце было не более 6 предложений. Добавить к первом абзацу отступ с пробелами. Например, ⋅⋅⋅Три пробела перед абзацем образуют отступ.
Используйте три дефиса (---) для создания горизонтальной черты. Используйте горизонтальные линии для обозначения конца в содержании абзаца. Например, смена места в истории или переход темы в разделе. Используйте горизонтальные линии для оформления.

Ссылки

Можно делать и нельзя - Ссылки
Можно Нельзя
Указывайте ссылки, которые передают суть содержания, на который они ссылаются. Например: "Некоторые порты открыты на ваших машинах. Смотрите раздел Проверка необходимых портов, чтобы получить дополнительную информацию". Используйте двусмысленные термины, такие как "нажмите сюда". Например: Некоторые порты открыты на ваших машинах. Смотрите этот раздел, чтобы получить дополнительную информацию".
Указывайте ссылки в стиле Markdown: [текст ссылки](URL). Например: [Макрокоды Hugo](/docs/contribute/style/hugo-shortcodes/#table-captions) отобразится как Макрокоды Hugo. Указывайте ссылки в формате HTML: <a href="/media/examples/link-element-example.css" target="_blank">Ознакомьтесь с нашим руководством!</a> или добавляйте ссылки, которые открываются в новых вкладках или окнах. Например: [example website](https://example.com){target="_blank"}

Списки

Сгруппируйте пункты в списке так, чтобы они были связаны друг с другом и следовали в определённом порядке, либо чтобы они сохраняли взаимосвязь между несколькими элементами. Когда программа чтения с экрана встречает нумерованный или неупорядоченный список, пользователю будет проинформирован, что существует группа из элементов списка. Затем пользователь может использовать клавиши-стрелки для перемещения между разными элементами в списке. Навигационные ссылки по сайту также могут быть помечены как элементы списка; в конечном счёте, все они просто группа связанных ссылок.

  • Заканчивайте каждый элемент в списке точкой, если один или несколько элементов в списке являются законченными предложениями. Как правило, для согласованности либо все элементы должны быть целыми предложениями, либо ни один из них.

  • Используйте цифру один (1.) для упорядоченных списков.

  • Используйте (+), (*) или (-) для неупорядоченных списков.

  • Добавьте пустую строку после каждого списка.

  • Во вложенных списках добавьте отступ в четыре пробела (например, ⋅⋅⋅⋅).

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

Таблицы

Семантическая цель таблицы данных состоит в представлении данных в табличном виде. Пользователи с нормальным зрением могут бегло просмотреть таблицу, однако программа для чтения с экрана сканирует таблицу построчно. Заголовок таблицы используется для создания информативного заголовка для табличных данных. Инструменты вспомогательных технологий (Assistive technologies, AT) используют элемент заголовка HTML-таблицы, чтобы идентифицировать для пользователей, какие на странице есть таблицы.

  • Добавьте подписи к таблицам с помощью соответствующих макрокодов Hugo.

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

В этом разделе перечислены рекомендации для написания ясного, лаконичного и единообразного текста документации.

Используйте настоящее время

Можно делать и нельзя - Используйте настоящее время
Можно Нельзя
Эта команда запускает прокси. Эта команда запустит прокси.

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

Используйте действительный залог

Можно делать и нельзя - Используйте действительный залог
Можно Нельзя
Вы можете изучить API с помощью браузера. API можно изучить с помощью браузера.
В файле YAML определяется количество реплик. Количество реплик определяется в файле YAML.

Исключение: используйте страдательный залог, если в действительном залоге получается неудачная формулировка.

Используйте простой и понятный язык

Используйте простой и доступный язык. Избегайте использования ненужных фраз, например, "пожалуйста".

Можно делать и нельзя - Используйте простой и понятный язык
Можно Нельзя
Чтобы создать ReplicaSet, ... Для того чтобы создать a ReplicaSet, ...
Смотрите конфигурационный файл. Пожалуйста, смотрите конфигурационный файл.
Посмотрите Pods. С помощью следующей команды мы посмотрим Pods.

Обращайтесь к читателю на "вы"

Можно делать и нельзя - Обращайтесь к читателю на вы
Можно Нельзя
Вы можете создать Deployment с помощью ... Мы создадим Deployment с помощью ...
В предыдущем выводе вы можете увидеть ... В предыдущем выводе мы можем увидеть ...

Избегайте использования латинских фраз

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

Можно делать и нельзя - Избегайте использования латинских фраз
Можно Нельзя
For example, ... e.g., ...
That is, ... i.e., ...

Исключение: используйте "etc." вместо "et cetera".

Ошибки, которые следует избегать

Избегайте использования "мы"

Использование "мы" в предложении может сбить с толку, так так неясно, кто под этим "мы" подразумевается (имеется ли в виду сам читатель при этом).

Можно делать и нельзя - Избегайте использования мы
Можно Нельзя
Версия 1.4 включает в себя ... В версии 1.4 мы добавили ...
Kubernetes представляет новую возможность для ... Мы представляем новую возможность ...
На этой странице вы узнаете, как использовать Pods. На этой странице мы познакомимся с Pods.

Избегайте жаргона и идиомы

Некоторые читатели говорят на английском как на втором языке. Избегайте жаргона и идиом, чтобы облегчить им понимание.

Можно делать и нельзя - Избегайте жаргона и идиомы
Можно Нельзя
Internally, ... Under the hood, ...
Create a new cluster. Turn up a new cluster.

Избегайте выражений о будущем

Не давайте обещаний или намеков на будущее. Если вам нужно рассказать про функциональность в альфа-версии, под соответствующем заголовком напишите поясняющий текст, что информация относится к альфа-версии.

Избегайте выражений, которые могут потерять актуальность

Избегайте таких слов, как "в настоящее время" и "новый". Новая функциональность в настоящее время не будет таковой через несколько месяцев.

Можно делать и нельзя - Избегайте выражений, которые могут потерять актуальность
Можно Нельзя
В версии 1.4 ... В текущей версии ...
Функциональность Federation предоставляет ... Новая функциональность Federation предоставляет ...

Что дальше

2 - Руководство по содержанию документации

Эта страница содержит рекомендации по добавлению контента в документацию Kubernetes. Если у вас есть вопросы по поводу допустимого контента, обратитесь к каналу #sig-docs в Slack Kubernetes и задайте свои вопросы! Поступайте на своё усмотрение и не стесняйтесь вносить изменения в этот документ через пулреквест.

Для получения дополнительной информации о создании нового контента для документации Kubernetes следуйте инструкциям в руководстве по оформлению.

Участие в контенте

Документация Kubernetes включает содержимое из оригинального репозитория kubernetes/website. Документация Kubernetes находится в директории kubernetes/website/content/<language_code>/docs, большая часть которой относится к проекту Kubernetes. Документация Kubernetes может также включать содержимое их проектов в GitHub-организациях kubernetes и kubernetes-sigs, если у этих проектов нет собственной документации. Всегда можно ссылаться на действующие проекты kubernetes, kubernetes-sigs и (CNCF) в документации Kubernetes, но перелинковка с продуктами определённого разработчика не допускается. Проверьте списки проектов CNCF (Graduated/Incubating, Sandbox, Archived), если вы не уверены в статусе CNCF проекта

Контент, полученный из двух источников

Документация Kubernetes не содержит дублированный контент, полученный из разных мест (так называемый контент из двух источников). Контент из двух источников требует дублирования работы со стороны мейнтейнеров проекта и к тому же быстро теряет актуальность. Перед добавлением контента, задайте себе вопрос:

  • Новая информация относится к действующему проекту CNCF или проекту в организациях на GitHub kubernetes или kubernetes-sigs?
    • Если да, то:
      • У этого проекта есть собственная документация?
        • если да, то укажите ссылку на документацию проекта в документации Kubernetes.
        • если нет, добавьте информацию в репозиторий проекта (если это возможно), а затем укажите ссылку на неё в документации Kubernetes.
    • Если нет, то:
      • Остановитесь!
        • Добавление информации о продуктах от других разработчиков не допускается.
        • Не разрешено ссылаться на документацию и сайты сторонних разработчиков.

Разрешенная и запрещённая информация

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

  1. Инструкции по установке или эксплуатации Kubernetes, которые не связаны с проектами Kubernetes.

    • Разрешено:
      • Ссылаться на документацию CNCF-проекта или на проект в GitHub-организациях kubernetes или kubernetes-sigs.
        • Пример: для установки Kubernetes в процессе обучения нужно обязательно установить и настроить minikube, а также сослаться на соответствующую документацию minikube.
      • Добавление инструкций для проектов в организации kubernetes или kubernetes-sigs, если по ним нет инструкций.
        • Пример: добавление инструкций по установке и решению неполадок kubeadm.
    • Запрещено:
      • Добавление информации, которая дублирует документацию в другом репозитории.
        • Примеры:
          • Добавление инструкций по установке и настройке minikube; Minikube имеет собственную документацию, которая включают эти инструкции.
          • Добавление инструкций по установке Docker, CRI-O, containerd и других окружений для выполнения контейнеров в разных операционных системах.
          • Добавление инструкций по установке Kubernetes в промышленных окружениях, используя разные проекты:
            • Kubernetes Rebar Integrated Bootstrap (KRIB) — это проект стороннего разработчика, поэтому всё содержимое находится в репозитории разработчика.
            • У проекта Kubernetes Operations (kops) есть инструкции по установке и руководства в GitHub-репозитории.
            • У проекта Kubespray есть собственная документация.
      • Добавление руководства, в котором объясняется, как выполнить задачу с использованием продукта определенного разработчика или проекта с открытым исходным кодом, не являющиеся CNCF-проектами или проектом в GitHub-организациях kubernetes, или kubernetes-sigs.
      • Добавление руководства по использованию CNCF-проекта или проекта в GitHub-организациях kubernetes или kubernetes-sigs, если у проекта есть собственная документация.
  2. Подробное описание технических аспектов по использованию стороннего проекта (не Kubernetes) или как этот проект разработан.

    Добавление такого типа информации в документацию Kubernetes не допускается.

  3. Информация стороннему проекту.

    • Разрешено:
      • Добавление краткого введения о CNCF-проекте или проекте в GitHub-организациях kubernetes или kubernetes-sigs; этот абзац может содержать ссылки на проект.
    • Запрещено:
      • Добавление информации по продукту определённого разработчика.
      • Добавление информации по проекту с открытым исходным кодом, который не является CNCF-проектом или проектом в GitHub-организациях kubernetes или kubernetes-sigs.
      • Добавление информации, дублирующего документацию из другого проекта, независимо от оригинального репозитория.
        • Пример: добавление документации для проекта Kubernetes in Docker (KinD) в документацию Kubernetes.
  4. Только ссылки на сторонний проект.

    • Разрешено:
      • Ссылаться на проекты в GitHub-организациях kubernetes и kubernetes-sigs.
        • Пример: добавление ссылок на документацию проекта Kubernetes in Docker (KinD), который находится в GitHub-организации kubernetes-sigs.
      • Добавление ссылок на действующие CNCF-проекты.
        • Пример: добавление ссылок на документацию проекта Prometheus; Prometheus — это действующий проект CNCF.
    • Запрещено:
      • Ссылаться на продукты стороннего разработчика.
      • Ссылаться на прекращенные проекты CNCF.
      • Ссылаться на недействующие проекты в организациях GitHub в kubernetes и kubernetes-sigs.
      • Ссылаться на проекты с открытым исходным кодом, которые не являются проектами CNCF или не находятся в организациях GitHub kubernetes, или kubernetes-sigs.
  5. Содержание учебных курсов.

    • Разрешено:
    • Запрещено:
      • Ссылаться на учебные онлайн-курсы, не относящиеся к CNCF, Linux Foundation или Linux Academy; документация Kubernetes не содержит ссылок на сторонний контент.
        • Пример: добавление ссылок на учебные руководства или курсы Kubernetes на Medium, KodeKloud, Udacity, Coursera, learnk8s и т.д.
      • Ссылаться на руководства определённых разработчиков вне зависимости от обучающей организации.

Если у вас есть вопросы по поводу допустимого контента, присоединяйтесь к каналу #sig-docs в Slack Kubernetes!

Что дальше

3 - Написание новой темы

На этой странице показано, как создать новую тему для документации Kubernetes.

Подготовка к работе

Создайте копию репозитория документации Kubernetes, как описано в разделе Участие для начинающих.

Выбор типы страницы

Перед написанием новой темы, выберите тип страницы, который бы лучше всего подходил под ваш текст:

Правила выбора типа страницы
Тип Описание
Концепция Страница концепции объясняет некоторые аспекты Kubernetes. Например, страницы концепции может описывать объект Deployment в Kubernetes и разъяснить, какую роль он играет после развертывания, масштабирования и обновления приложения. Как правило, страницы концепций не включают последовательности шагов, а вместо этого содержат ссылки на задачи или руководства. В качестве примера концептуальной темы посмотрите страницу Nodes.
Задача На странице задачи показывается, как сделать что-то одно конкретное, главным образом с помощью короткой последовательности шагов. Страница задачи может быть короткой или длинной, если она остаётся сконцентрированной на одном аспекте. На странице задач можно сочетать краткие объяснения с необходимыми шагами для выполнения, однако если вам нужно дать подробное пояснение, вам следует сделать это в концептуальной теме. Смежные задачи и концептуальные темы должны быть связаны друг с другом. В качестве примера короткой страницы задачи посмотрите Configure a Pod to Use a Volume for Storage. Пример длинной страницы задачи смотрите Configure Liveness and Readiness Probes
Руководство На странице руководства показано, как сделать что-то более крупнее одной-единственной задачи. В руководстве может быть несколько последовательностей шагов, которые читатели могут реально выполнить по ходу чтения страницы. Либо на странице руководства могут приведены объяснения связанных частей кода. Например, руководство может содержать разбор примера кода. Руководство может включать в себя краткие объяснения связанной функциональности Kubernetes, но при они этом должны ссылаться на сопутствующие концептуальные темы, где можно узнать подробнее про конкретные возможности.

Используйте шаблон для каждой новой страницы. Каждый тип страницы использует определённый шаблон, поэтому при написании собственных тем вам следует выбрать свой шаблон. Использование шаблонов помогает поддерживать единообразие в темах конкретного типа.

Выбор заголовка и имени файла a title and filename

Подберите заголовок, содержащий такие ключевые слова, по которым вы могли его найти в поисковике. Имя файла должно создаваться из слов в заголовке, написанных через дефис. Например, для темы с заголовком Using an HTTP Proxy to Access the Kubernetes API имя файла будет http-proxy-access-api.md. Вам не нужно указывать "kubernetes" в имени файла, потому что слово "kubernetes" уже есть в полном URL-адресе темы, например:

   /docs/tasks/access-kubernetes-api/http-proxy-access-api/

Добавление заголовка темы в фронтальную часть

В фронтальную часть файла вашей темы поместите поле заголовка title. Фронтальная часть — YAML-блок, который находится тремя дефисами в самом верху страницы. Например:

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

Выбор директории

В зависимости от типа вашей страницы поместите новый файл в одну из следующую поддиректорию:

  • /content/en/docs/tasks/
  • /content/en/docs/tutorials/
  • /content/en/docs/concepts/

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

Добавление темы в оглавлении

Оглавление динамически генерируется исходя из структуры директорий документации. Корневые директории в /content/en/docs/ создают навигацию с основными ссылками, где у каждой поддиректории есть записи в оглавлении.

В каждой поддиректории есть файл _index.md, представляющий собой "главную" страницу всего содержимого этой поддиректории. В файле _index.md не нужно применять шаблон. В нём находится обзор содержания тем в поддиректории.

Другие файлы в директории по умолчанию сортируются в алфавитном порядке. Такой порядок сортировки редко устраивает. Для управления такой относительной сортировкой тем в поддиректории, определите ключ weight: с целым числом в фронтальной части файла. Как правило, мы используем значения, кратные 10, чтобы оставить про запас для будущих страниц. Например, тема с весом 10 будет отображаться перед темой с весом 20.

Вставка кода в тему

Если вы хотите добавить код в тему, вы можете встроить код из файла напрямую, используя синтаксис блока кода в Markdown. Такой способ рекомендуется использовать в следующих случаев (это не исчерпывающий список):

  • В вашем коде показывается вывод такой команды, как kubectl get deploy mydeployment -o json | jq '.status'.
  • Ваш код недостаточно универсален, чтобы пользователи могли его попробовать сами. В качестве примера можно привести пример YAML-файла для создания Pod, который зависит от конкретной реализации FlexVolume.
  • Ваш код — это не готовый пример, потому что он предзначен для выделения части большего файла. Например, при описании способов настройки PodSecurityPolicy по определённым причинам вы можете включить небольшой фрагмент напрямую в файле темы.
  • Ваш код по разным причинам не подходит для тестирования пользователями. Например, если вы описываете, как новый атрибут должен добавляться к ресурсу с помощью команды kubectl edit, то вы можете добавить короткий пример, показывающий только добавляемый атрибут.

Добавление кода из другого файла

Другой способ добавить код в вашу тему — создать новый полноценный файл с примером (или группу файлов примеров), а затем из вашей темы подключить этот пример. Используйте этот метод, чтобы включить универсальный и повторно используемый пример YAML-файла, который читатель может проверить сам.

При добавлении нового отдельного файла примера, например, в формате YAML, поместите код в одну из директорий <LANG>/examples/, где <LANG> — язык темы. В вашем файле темы используйте макрокод codenew:

{{% codenew file="<RELPATH>/my-example-yaml>" %}}

где <RELPATH> — это путь к включаемому файлу относительно директории examples. Следующий макрокод Hugo ссылается на YAML-файл по пути /content/en/examples/pods/storage/gce-volume.yaml.

{{% codenew file="pods/storage/gce-volume.yaml" %}}

Демонстрация создания API-объекта из конфигурационного файла

Если вам нужно показать, как создать объект API из файла конфигурации, поместите файл конфигурации в одну из директорий в <LANG>/examples.

В вашей теме укажите эту команду:

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

В качестве примера темы, в которой используется этот метод, смотрите Running a Single-Instance Stateful Application.

Добавление изображений в тему

Поместите файлы изображений в директорию /images. Предпочтительный формат изображения — SVG.

Что дальше

4 - Использование шаблонов страниц

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

Шаблоны страниц находятся в директории layouts/partials/templates репозитория kubernetes/website.

Шаблон концепции

Страница концепции объясняет некоторые аспекты Kubernetes. Например, страницы концепции может описывать объект Deployment в Kubernetes и разъяснить какую роль он играет после развертывания, масштабирования и обновления приложения. Как правило, страницы концепций не включают последовательности шагов, и вместо этого содержат ссылки на задачи или руководства.

Для написания новой страницы концепции в директории /content/en/docs/concepts создайте поддиректорию с Markdown-файлом со следующим требованиями:

  • Во фронтальной части YAML этой страницы определите поле content_type: concept.

  • В теле страницы укажите переменные capture и любые другие, которые вы хотите включить:

    Переменная Обязательна?
    overview да
    body да
    whatsnext нет

    Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не понадобятся):

    {{% capture overview %}}
    
    {{% /capture %}}
    
    {{% capture body %}}
    
    {{% /capture %}}
    
    {{% capture whatsnext %}}
    
    {{% /capture %}}
    
  • Заполните каждый раздел информацией. Следуйте этим рекомендациям:

    • Структурируйте контент с помощью заголовков H2 и H3.
    • В блоке overview одним абзацем сформируйте контекст темы.
    • В блоке body объясните суть концепции.
    • В блоке whatsnext сформируйте ненумерованный список тем (до 5), к которым нужно обратиться, чтобы получить дополнительную информацию о концепции.

Annotations — это готовый пример шаблона концепции. Кстати, текущая страница использует шаблон концепции.

Шаблон задачи

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

Для написания новой страницы задачи в директории /content/en/docs/tasks создайте поддиректорию с Markdown-файлом со следующим требованиями:

  • Во фронтальной части YAML этой страницы определите поле content_type: task.

  • В теле страницы укажите переменные capture и любые другие, которые вы хотите включить:

    Переменная Обязательна?
    overview да
    prerequisites да
    steps нет
    discussion нет
    whatsnext нет

    Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не нужны):

    {{% capture overview %}}
    
    {{% /capture %}}
    
    {{% capture prerequisites %}}
    
    {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
    
    {{% /capture %}}
    
    {{% capture steps %}}
    
    {{% /capture %}}
    
    {{% capture discussion %}}
    
    {{% /capture %}}
    
    {{% capture whatsnext %}}
    
    {{% /capture %}}
    
  • Заполните каждый блок информацией. Следуйте этим рекомендациям:

    • Используйте по минимуму заголовков H2 (с двумя ведущими символами #). У самих разделов заголовок формируется автоматически по заданному шаблону.
    • В блоке overview обозначьте контекст для всей темы.
    • В блоке prerequisites используйте ненумерованные списки, где это возможно. Добавьте дополнительные предварительные условия ниже include. Предварительные условия по умолчанию содержат пункт про наличие работающего кластера.
    • В блоке steps используйте нумерованные списки.
    • В блоке discussion подробно распишите информацию, описанную в разделе steps.
    • В блоке whatsnext сформируйте ненумерованный список тем (до 5), которые могут быть интересны читателю в качестве дополнительного чтения.

Пример готовой темы, в которой используется шаблон задачи — Using an HTTP proxy to access the Kubernetes API.

Шаблон руководства

На странице руководства показывается, как выполнить что-то более крупнее одной-единственной задачи. Как правило, страницы руководства поделена на несколько разделов, в каждом из которых есть последовательность шагов. Например, руководство может включать анализ примера кода, демонстрирующий определенную возможность Kubernetes. Руководства могут содержать поверхностные объяснения и одновременно включать ссылки на соответствующие концептуальные темы для получения углубленных знаний.

Для написания новой страницы задачи в директории /content/en/docs/tutorials создайте поддиректорию с Markdown-файлом со следующим требованиями:

  • Во фронтальной части YAML этой страницы определите поле content_type: tutorial.

  • В теле страницы укажите переменные capture и любые другие, которые вы хотите включить:

    Переменная Обязательна?
    overview да
    prerequisites да
    objectives да
    lessoncontent да
    cleanup нет
    whatsnext нет

    Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не понадобятся):

    {{% capture overview %}}
    
    {{% /capture %}}
    
    {{% capture prerequisites %}}
    
    {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
    
    {{% /capture %}}
    
    {{% capture objectives %}}
    
    {{% /capture %}}
    
    {{% capture lessoncontent %}}
    
    {{% /capture %}}
    
    {{% capture cleanup %}}
    
    {{% /capture %}}
    
    {{% capture whatsnext %}}
    
    {{% /capture %}}
    
  • Заполните каждый блок информацией. Следуйте этим рекомендациям:

    • Используйте по минимуму заголовков H2 (с двумя ведущими символами #). У самих разделов заголовок формируется автоматически по заданному шаблону.
    • В блоке overview обозначьте контекст для всей темы.
    • В блоке prerequisites используйте ненумерованные списки, где это возможно. Добавьте дополнительные предварительные условия ниже include. Предварительные условия по умолчанию содержат пункт про наличие работающего кластера.
    • В блоке objectives используйте ненумерованные списки.
    • В блоке lessoncontent целесообразно используйте совместно нумерованные списки и повествовательное содержание.
    • В блоке cleanup используйте нумерованные списки для описания шагов для очистки состояния кластера после выполнения задачи.
    • В блоке whatsnext сформируйте ненумерованный список тем (до 5), которые могут быть интересны читателю в качестве дополнительного чтения.

Пример завершенной темы, в которой используется шаблон руководства — Running a Stateless Application Using a Deployment.

Что дальше

5 - Организация контента

Этот сайт использует Hugo. В Hugo организация контента — основная концепция.

Списки страниц

Порядок страницы

Меню в сайдбаре, каталог страниц документации используют стандартный порядок перечисления Hugo, который сортирует элементы по весу (от 1), дате (начиная с самых новых) и затем по заголовку ссылки.

Таким образом, если вам нужно поднять страницу или раздел, определите её вес в фронтальной части:

title: Моя страница
weight: 10

Главное меню документации

Главное меню Документация состоит из разделов по пути docs/ с установленным флагом main_menu в фронтальной части файла раздела _index.md:

main_menu: true

Обратите внимание, что текст ссылки берётся из переменной linkTitle, поэтому, если вы хотите, чтобы он отличался от заголовка страницы, измените его в файле:

main_menu: true
title: Название страницы
linkTitle: Название, которое будет использоваться в ссылках

Документация в боковом меню

Меню сайдбара в документации собирается из текущего дерева разделов по пути docs/.

Оно отобразит все разделы и их страницы.

Если вы хотите, чтобы раздел или страница не отображались в меню, установите для флага toc_hide значение true в фронтальной части файла:

toc_hide: true

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

Каталог документации

Каталог страниц на главной странице документации сгенерирован с учётом всех разделов и страниц документации.

Если вы хотите скрыть раздел или страницу, установите для флага toc_hide значение true в фронтальной части файла:

toc_hide: true

Главное меню

Ссылки сайта в верхнем правом меню, а также в футере, создаются посредством сканирования страниц. Этот процесс гарантирует, что страница действительно существует на сайте. Поэтому, если раздела case-studies на сайте (или в переводе) не существует, ссылка не появится.

Пакеты страниц

В дополнение к отдельным страницам с контентом (Markdown-файлам), Hugo поддерживает пакеты страниц (page bundles).

К примеру, пользовательские макрокоды Hugo — узел пакета (leaf bundle). Все, что находится в директории, включая index.md, будет частью пакета. Сюда также относятся относительные ссылки на страницы, изображения, которые могут быть обработаны и т.д.:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Другой распространённый пример — это пакет includes. Он устанавливает переменную headless: true, которая означает, что файл не будет доступен по собственному URL-адресу. Вместо этого он будет использоваться в других страницах как вставляемый файл.

en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Необходимо отметить следующие особенности файлов в пакетах:

  • Для переведенных пакетов любые отсутствующие файлы будут унаследованы от файлов на оригинальном (английском) языке. Это позволяет избежать дублирования.
  • Все файлы в пакете — в Hugo называются ресурсы (Resources), в которых вы можете определить метаданные, зависимые от языка, например, параметры и заголовок, даже если они не поддерживают в фронтальной части (YAML-файлы и т.д.). Смотрите Метаданные ресурсов страницы для получения дополнительной информации.
  • Значение, которое вы получаете через .RelPermalink в Resource будет отличаться в зависимости от страницы. Смотрите Постоянные ссылки для получения дополнительной информации.

Стилизация

Исходные файлы стилей в формате SASS находятся в директории assets/sass и автоматически собираются Hugo.

Что дальше

6 - Пользовательские макрокоды Hugo

На этой странице объясняются пользовательские макрокоды Hugo, которые можно использовать в Markdown-файлах документации Kubernetes.

Узнать подробнее про макрокоды можно в документации Hugo.

Состояние функциональности

В Markdown странице (файл с расширением .md) вы можете добавить макрокод, чтобы отобразить версию и состояние документированной функциональной возможности.

Демонстрация состояния функциональности

Ниже показан фрагмент кода для вывода состояния функциональности, который сообщает о функциональности в стабильной версии Kubernetes 1.10.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Результат:

СТАТУС ФИЧИ: Kubernetes v1.10 [stable]

Допустимые значения для state:

  • alpha
  • beta
  • deprecated
  • stable

Код состояния функциональности

По умолчанию отображается версия Kubernetes, соответствующая версии страницы или сайта. Это значение можно переопределить, передав параметр макрокода for_k8s_version.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Результат:

СТАТУС ФИЧИ: Kubernetes v1.10 [stable]

Функциональность в альфа-версии

{{< feature-state state="alpha" >}}

Результат:

СТАТУС ФИЧИ: Kubernetes v1.28 [alpha]

Функциональность в бета-версии

{{< feature-state state="beta" >}}

Результат:

СТАТУС ФИЧИ: Kubernetes v1.28 [beta]

Функциональность в стабильной версии

{{< feature-state state="stable" >}}

Результат:

СТАТУС ФИЧИ: Kubernetes v1.28 [stable]

Устаревшая функциональность

{{< feature-state state="deprecated" >}}

Результат:

СТАТУС ФИЧИ: Kubernetes v1.28 [deprecated]

Глоссарий

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

Исходные файлы терминов глоссария хранятся в отдельной директории по URL-адресу https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary.

Демонстрация глоссария

Например, следующий фрагмент кода в Markdown будет отображен в виде всплывающей подсказки — cluster:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Заголовки таблиц

Для улучшения доступности таблиц для программ для чтения с экрана, добавьте заголовок к таблице. Чтобы добавить заголовок таблицы, поместите таблицу в макрокод table и определите значение заголовка в параметре caption.

Пример:

{{< table caption="Конфигурационные параметры" >}}
Параметр | Описание | Значение по умолчанию
:---------|:------------|:-------
`timeout` | Тайм-аут для запросов | `30s`
`logLevel` | Уровень логирования | `INFO`
{{< /table >}}

Результат:

{{< table caption="Конфигурационные параметры" >}}

Параметр Описание Значение по умолчанию
timeout Тайм-аут для запросов 30s
logLevel Уровень логирования INFO
{{< /table >}}

Если вы изучите HTML-код таблицы, вы заметите следующий ниже элемент сразу после открывающего элемента <table>:

<caption style="display: none;"></caption>

Вкладки

Страница в формате Markdown (файл с расширением .md) на этом сайте может содержать набор вкладок для отображения нескольких разновидностей определённого решения.

Макрокод tabs принимает следующие параметры:

  • name: имя, отображаемое на вкладке.
  • codelang: если вы указываете встроенный контент для макрокода tab, вы можете сообщить Hugo, какой язык использовать для подсветки синтаксиса.
  • include: включаемый файл в вкладку. Если вкладка находится в узле пакета (leaf bundle) Hugo, то файл (может быть любым MIME-типом, который поддерживает Hugo) ищется в самом пакете. Если нет, то включаемое содержимое ищется относительно текущей страницы. Обратите внимание, что при использовании include вам следует использовать самозакрывающийся синтаксис. Например, {{</* tab name="Content File #1" include="example1" />}}. Язык может быть указан в codelang, в противном случае язык определяется из имени файла.
  • Если содержимое вкладки это Markdown, вам нужно использовать символ %. Например, {{% tab name="Вкладка 1" %}}This is **markdown**{{% /tab %}}
  • Вы можете совместно использовать перечисленные выше параметры. Ниже приведена демонстрация шорткода вкладок.

Ниже приведены примеры вкладок.

Демонстрация вкладок: подсветка синтаксиса в блоках кода

{{< tabs name="tab_with_code" >}}
{{{< tab name="Вкладка 1" codelang="bash" >}}
echo "Это вкладка 1."
{{< /tab >}}
{{< tab name="Вкладка 2" codelang="go" >}}
println "Это вкладка 2."
{{< /tab >}}}
{{< /tabs >}}

Результат:


echo "Это вкладка 1."


println "Это вкладка 2."

Демонстрация вкладок: встроенный Markdown и HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
Это **разметка Markdown.**
{{< note >}}
Также можно использовать макрокоды.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Обычный HTML</h3>
	<p>Это <i>обычный</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Результат:

Это разметка Markdown.

Обычный HTML

Это обычный HTML.

Демонстрация вкладок: включение файлов

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Результат:

Это пример содержимого в файле внутри пакета узла includes.

Это другой пример содержимого в файле внутри пакета узла includes.

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

Что дальше