Генерация справочной документации для 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>.
• K8S_WEBROOT со значением <web-base>.
• K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17.0, определите переменную окружения K8S_RELEASE со значением 1.17.0.

Примеры:

export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
export K8S_RELEASE=1.17.0

Создание версионированной директории и получение 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/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/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. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

Что дальше

• Руководство по быстрому старту генерации справочной документации
• Генерация справочной документации для компонентов и инструментов Kubernetes
• Генерация справочной документации для команд kubectl