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

Edit This Page

Генерация справочной документации для API Kubernetes

На этой странице рассказывается про обновление справочной документации по API Kubernetes.

Справочная документация по API Kubernetes собирается из спецификации OpenAPI Kubernetes с использованием инструмента генерации kubernetes-sigs/reference-docs.

Если вы нашли баги в сгенерированной документации, то можете исправить их в основном коде.

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

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

Требования:

  • Наличие компьютера под управлением ОС Linux или macOS.

  • Установленные следующие инструменты:

    • Python версии 3.7.x
    • Git
    • Golang версии 1.13+
    • Pip, который потребуется для установки PyYAML
    • PyYAML версии 5.1.2
    • make
    • gcc compiler/linker
    • Docker (требуется только для справочника команды kubectl)

  • В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

  • Вам нужно знать, как создать пулреквест в репозитории на GitHub. Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел Работа из локальной копии.

Настройка локальных репозиториев

Создайте рабочую область и определите переменную окружения GOPATH.

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Загрузите локальные копии следующих репозиториев:

go get -u github.com/kubernetes-sigs/reference-docs

go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec

Если у вас ещё нет копии репозитория kubernetes/website, клонируйте её на свой компьютер:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

  • Определите базовую директорию вашей копии репозитория kubernetes/kubernetes. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/k8s.io/kubernetes. В остальных командах базовая директория будет именоваться как <k8s-base>.

  • Определите базовую директорию вашей копии репозитория kubernetes/website. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/<your-username>/website. В остальных командах базовая директория будет именоваться как <web-base>.

  • Определите базовую директорию вашей копии репозитория kubernetes-sigs/reference-docs. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/kubernetes-sigs/reference-docs. В остальных командах базовая директория будет именоваться как <rdocs-base>.

Генерация справочной документации API

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

Настройка переменных для сборки

  • K8S_ROOT со значением <k8s-base>.
  • WEB_ROOT со значением <web-base>.
  • K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения K8S_RELEASE со значением 1.17.

Примеры:

export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17

Создание версионированной директории и получение Open API spec

Скрипт сборки updateapispec создает версионированную директорию для сборки. После создания директории спецификация Open API генерируется из репозитория <k8s-base>. Таким образом версия конфигурационных файлов и спецификация Kubernetes Open API будут совпадать с версией выпуска. Имя версионированной директории имеет следующий вид: v<major>_<minor>.

В директории <rdocs-base> выполните следующий скрипт сборки:

cd <rdocs-base>
make updateapispec

Сборка справочной документации API

Скрипт сборки copyapi создает справочник API и копирует генерированные файлы в каталоги в <web-base>. Выполните следующую команду в <rdocs-base>:

cd <rdocs-base>
make copyapi

Убедитесь в том, что перечисленные ниже два файлы были сгенерированы:

[ -e "<rdocs-base>/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Перейдите в корень директории <web-base> и посмотрите, какие файлы были изменены:

cd <web-base>
git status

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

static/docs/reference/generated/kubernetes-api/v1.17/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.17/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.17/index.html
static/docs/reference/generated/kubernetes-api/v1.17/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.17/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.17/js/scroll.js

Обновление указателя API-справочника

При генерации справочной документации для нового выпуска в файле <web-base>/content/en/docs/reference/kubernetes-api/api-index.md нужно прописать номер предстоящей версии.

  • Откройте файл <web-base>/content/en/docs/reference/kubernetes-api/api-index.md и обновите номер версии справочника API. Например:

    ---
title: v1.17
---

[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)

  • Откройте файл <web-base>/content/en/docs/reference/_index.md и добавьте ссылку на последний справочник API. Удалите самую старую версию справочника API. В этом файле должно быть 5 ссылок на новейшие API-справочники.

Тестирование справочника API локально

Соберите обновлённую версию API-справочника на своём компьютере. Проверьте ваши изменения на локальной предварительной версии сайта.

cd <web-base>
make docker-serve

Фиксация изменений

В директории <web-base> выполните команду git add и git commit для фиксации изменений в репозитории.

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят.

Отправьте свои изменения в виде пулреквеста в репозиторий kubernetes/kubernetes. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

Что дальше

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