Генерація документації для API Kubernetes

Ця сторінка демонструє, як оновити документацію API Kubernetes.

Документація API Kubernetes формується на основі специфікації OpenAPI Kubernetes з використанням коду генерації з kubernetes-sigs/reference-docs.

Якщо ви знайшли помилки у згенерованій документації, вам потрібно виправити їх на upstream.

Якщо вам потрібно тільки згенерувати документацію з OpenAPI, продовжте читати цю сторінку.

Перш ніж ви розпочнете

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS.

  • Вам потрібно встановити ці інструменти:

  • Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

  • Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Налаштування локальних репозиторіїв

Створіть локальне робоче середовище і встановіть ваш GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Отримайте локальну копію наступних репозиторіїв:

git clone github.com/kubernetes-sigs/reference-docs

Перейдіть до теки gen-apidocs репозиторію reference-docs та встановіть необхідні пакунки Go:

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

Отримайте копію репозиторію kubernetes/kubernetes:

git clone https://github.com/kubernetes/kubernetes

  • Основна тека вашої копії kubernetes/kubernetes репозиторію є <your-path-to>/kubernetes/kubernetes. Подальші кроки використовують цю основну директорію як <k8s-base>.

  • Основна тека вашої копії kubernetes/website репозиторію є <your-path-to>/website. Подальші кроки використовують цю основну директорію як <web-base>.

  • Основна тека вашої копії kubernetes-sigs/reference-docs репозиторію є <your-path-to>/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=<your-path-to>/website
export K8S_ROOT=<your-path-to>/kubernetes
export K8S_RELEASE=1.17.0

Створення теки версії та завантаження специфікації Open API

Ціль збірки 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.35/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.35/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.35/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.35/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.35/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.35/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.35/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.35/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.35/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.35/index.html
static/docs/reference/generated/kubernetes-api/v1.35/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.35/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.35/js/scroll.js

Розташування та версії довідки API

Створені файли довідки API (версія HTML) копіюються в <web-base>/static/docs/reference/generated/kubernetes-api/v1.35/. Ця тека містить автономну документацію API у форматі HTML.

Примітка:

Markdown-версія довідки API, розташована в <web-base>/content/en/docs/reference/kubernetes-api/, генерується окремо за допомогою генератора gen-resourcesdocs.

Локальне тестування документації API

Опублікуйте локальну версію документації API. Перевірте локальний попередній перегляд.

cd <web-base>
git submodule update --init --recursive --depth 1 # якщо ще не зроблено
make container-serve

Коміт змін

У <web-base>, виконайте git add і git commit, щоб зафіксувати зміни.

Подайте ваші зміни як pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request, і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

Що далі