Участие в документации Kubernetes

Edit This Page

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

На этой странице показано, как создать новую тему для документации 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" >}}
Заметка: Чтобы отобразить Hugo-макрокоды в исходном виде, как в приведенном выше примере, поместите их в комментарии в стиле языка Си между < и >. Для примера посмотрите исходный код этой страницы.

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

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

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

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
Заметка: При добавлении новых YAML-файлов в директорию <LANG>/examples, убедитесь, что этот файл перечислен в файле <LANG>/examples_test.go. Подключённый к сайту Travis CI автоматически выполнит этот тестовый сценарий при отправке PR, чтобы проверить все примеры.

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

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

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

Что дальше

Обратная связь