Генерация справочной документации для API Kubernetes
На этой странице рассказывается про обновление справочной документации по API Kubernetes.
Справочная документация по API Kubernetes собирается из спецификации OpenAPI Kubernetes с использованием инструмента генерации kubernetes-sigs/reference-docs.
Если вы нашли баги в сгенерированной документации, то можете исправить их в основном коде.
Продолжайте чтение данной странице, если вы хотите перегенерировать справочную документацию из спецификации OpenAPI.
Подготовка к работе
Требования:
-
Наличие компьютера под управлением ОС Linux или macOS.
-
Установленные следующие инструменты:
-
В переменной окружении
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. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.