Оновлення довідкової документації

• 1: Швидкий старт з довідковою документацією
• 2: Генерація довідкової документації для релізу
• 3: Внесок у код Kubernetes
• 4: Генерація документації для API Kubernetes
• 5: Генерування довідкової документації для Configuration API
• 6: Генерація документації для команд kubectl
• 7: Генерація довідкової документації для метрик
• 8: Генерація довідкових сторінок для компонентів та інструментів Kubernetes
• 9:

1 - Швидкий старт з довідковою документацією

Ця сторінка показує, як використовувати скрипт update-imported-docs.py для генерації довідкової документації Kubernetes. Скрипт автоматизує налаштування збірки та генерує довідкову документацію для релізу.

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

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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

Отримання репозиторію документації

Переконайтеся, що ваш форк репозиторію website синхронізований з віддаленим репозиторієм kubernetes/website на GitHub (гілка main), і клонуйте ваш форк website собі локально.

mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git

Визначте базову теку вашого клону. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — github.com/website. Наступні кроки посилаються на вашу базову теку як <web-base>.

Огляд update-imported-docs

Скрипт update-imported-docs.py розташований у теці <web-base>/update-imported-docs/.

Скрипт будує наступні довідки:

• Довідкові сторінки компонентів та інструментів
• Довідка по команді kubectl
• Довідка по API Kubernetes

Скрипт update-imported-docs.py генерує довідкову документацію Kubernetes з вихідного коду Kubernetes. Скрипт створює тимчасову теку в /tmp на вашій машині та клонує потрібні репозиторії: kubernetes/kubernetes та kubernetes-sigs/reference-docs у цю теку. Скрипт встановлює вашу змінну середовища GOPATH на цю тимчасову теку. Встановлюються три додаткові змінні середовища:

• K8S_RELEASE
• K8S_ROOT
• K8S_WEBROOT

Скрипт потребує два аргументи для успішного виконання:

• YAML конфігураційний файл (reference.yml)
• Версія релізу, наприклад: 1.17

Конфігураційний файл містить поле generate-command. Поле generate-command визначає серію інструкцій для збірки з kubernetes-sigs/reference-docs/Makefile. Змінна K8S_RELEASE визначає версію релізу.

Скрипт update-imported-docs.py виконує наступні кроки:

1. Клонування повʼязаних репозиторіїв, зазначених у конфігураційному файлі. Для генерації довідкових документів типово клонуються kubernetes-sigs/reference-docs.
2. Запуск команд під час клонування репозиторіїв для підготовки генератора документації та генерація HTML і Markdown файлів.
3. Копіювання згенерованих HTML і Markdown файлів до локального клону репозиторію <web-base> за вказаними в конфігураційному файлі шляхами.
4. Оновлення посилань команд kubectl з kubectl.md у секції в довідці по команді kubectl.

Коли згенеровані файли знаходяться у вашому локальному клоні репозиторію <web-base>, ви можете подати їх у pull request до <web-base>.

Формат конфігураційного файлу

Кожен конфігураційний файл може містити кілька репозиторіїв, які будуть імпортовані разом. За необхідності, ви можете налаштувати конфігураційний файл, редагуючи його вручну. Можна створювати нові конфігураційні файли для імпорту інших груп документів. Ось приклад YAML конфігураційного файлу:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Окремі Markdown документи, імпортовані за допомогою інструмента, повинні відповідати Посібнику зі стилю документації.

Налаштування reference.yml

Відкрийте <web-base>/update-imported-docs/reference.yml для редагування. Не змінюйте вміст поля generate-command, якщо не розумієте, як команда використовується для побудови довідок. Оновлення reference.yml зазвичай не потрібне. Іноді зміни в upstream вихідному коді можуть вимагати змін у конфігураційному файлі (наприклад: залежності версій golang та зміни сторонніх бібліотек). Якщо ви стикаєтеся з проблемами збірки, зверніться до команди SIG-Docs у #sig-docs Kubernetes Slack.

У reference.yml, files містить список полів src та dst. Поле src містить розташування згенерованого Markdown файлу у теці збірки kubernetes-sigs/reference-docs, а поле dst визначає, куди скопіювати цей файл у клонованому репозиторії kubernetes/website. Наприклад:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Зверніть увагу, що коли є багато файлів для копіювання з одного джерела в одну й ту ж теку призначення, ви можете використовувати шаблони в значенні src. Ви повинні надати назву теки як значення для dst. Наприклад:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Запуск інструмента update-imported-docs

Ви можете запустити інструмент update-imported-docs.py наступним чином:

cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>

Наприклад:

./update-imported-docs.py reference.yml 1.17

Виправлення посилань

Конфігураційний файл release.yml містить інструкції для виправлення відносних посилань. Щоб виправити відносні посилання у ваших імпортованих файлах, встановіть властивість gen-absolute-links на true. Ви можете знайти приклад цього в release.yml.

Додавання та коміт змін у репо kubernetes/website

Перегляньте файли, що були згенеровані та скопійовані до <web-base>:

cd <web-base>
git status

Вивід показує нові та змінені файли. Згенеровані результати варіюються залежно від змін, внесених у upstream вихідний код.

Згенеровані файли компонентів інструментів

content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

Згенеровані файли довідки команди kubectl

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/css/font-awesome.min.css

Згенеровані теки та файли довідки по Kubernetes API

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

Виконайте git add та git commit, щоб зафіксувати файли.

Створення pull request

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

Через кілька хвилин після злиття вашого pull request, ваша оновлена довідкова документація буде видна в опублікованій документації.

Що далі

Щоб перегенерувати кожен набір довідки для релізу та подати результат як pull request-и, дивіться Генерація довідкової документації для релізу.

Щоб згенерувати окрему довідкову документацію, вручну налаштувавши необхідні репозиторії та запустивши цільові завдання збірки, дивіться наступні посібники:

• Генерація довідкової документації для компонентів і інструментів Kubernetes
• Генерація довідкової документації для команд kubectl
• Генерація довідкової документації для API Kubernetes

2 - Генерація довідкової документації для релізу

Ця сторінка показує, як перегенерувати кожен набір довідкової документації Kubernetes для нового релізу та як розділити згенерований результат на pull request-и, які рецензенти можуть обробляти по одному.

Опрацьовуйте розділи по порядку. Кожен набір довідки має власний розділ, який збирає його, копіює у ваш клон вебсайту та завершується сторінкою для перевірки, тому ви можете завершити один набір, перш ніж почати наступний. Підсумок у кінці перелічує кожну ціль, її результат та pull request-и, які потрібно відкрити.

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

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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

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

Вам потрібні локальні клони kubernetes/website та kubernetes-sigs/reference-docs.

Якщо ви ще не зробили форк і клон kubernetes/website, дивіться Робота з локальним клоном. Клонуйте reference-docs:

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

Подальші кроки посилаються на ваш клон kubernetes/website як <web-base> та ваш клон reference-docs як <rdocs-base>.

Налаштування змінних збірки

Встановіть їх у вашій оболонці. Вони застосовуються до кожної команди make у кроках, що наведені нижче.

export K8S_WEBROOT=<your-path-to>/website     # ваш клон вебсайту (<web-base>)
export K8S_RELEASE=1.38.0

Встановіть K8S_RELEASE на повну версію релізу, наприклад 1.38.0 або 1.38.0-rc.1. Цілі збірки виводять назву теки з версією, наприклад v1_38, з основної та другої частин версії.

Створення тек з версіями

Виконайте це у <rdocs-base>:

make createversiondirs

Це створює теку конфігурації для нового релізу у gen-apidocs/config/, копіюючи config.yaml з попереднього релізу.

Вам рідко потрібно редагувати цей файл. Налаштування, які змінюються з кожним релізом: групи API та список ресурсів, які є порожніми, цілі збірки на цій сторінці передають --auto-detect, тому генератор читає їх з swagger.json. Те, що залишається у файлі, — це найменування та виключення операцій, які слідують за механізмами API, а не за його поверхнею.

Коли згенерована довідка виглядає неправильно, виправте причину в upstream, де можете: описи та повідомлення про застарілість походять з Go-коментарів у kubernetes/kubernetes, і виправлення там досягне кожного читача цього API. Редагуйте config.yaml лише для того, що вирішує сам генератор, наприклад операція без назви (operation_categories), точка доступу, яку довідка не має публікувати (excluded_operations), або група, чиї ідентифікатори операцій пишуться інакше, ніж її ресурси (operation_group_map). Кожен запис переноситься у кожен подальший реліз, тому тримайте файл стислим.

Отримання специфікації OpenAPI

Генератор довідки API читає gen-apidocs/config/<version>/swagger.json. Специфікація, яку комітить kubernetes/kubernetes, збирається з вимкненою функціональною можливістю OpenAPIEnums, тому вона пропускає допустимі значення перелічуваних полів, і довідка, зібрана з неї, також пропускає їх. Краще згенерувати довідку, яка перелічує допустимі значення, тому ви виконуєте кілька додаткових кроків, щоб цього досягти.

Виберіть один із двох наведених варіантів.

Варіант 1: Генерація специфікації з вихідного коду

Використовуйте цей варіант, якщо не можете виконати вимоги нижче. Він не потребує власного клону kubernetes/kubernetes, не чіпає жоден клон, який у вас уже є, і створює специфікацію, що включає значення переліків.

make updateapispec-enums-from-source

Ця ціль робить поверхневий клон kubernetes/kubernetes з тегу v$K8S_RELEASE у тимчасову теку, вмикає OpenAPIEnums=true лише у цьому клоні, запускає upstream hack/update-openapi-spec.sh, копіює отриману специфікацію у теку конфігурації з версією, перевіряє, що вона містить значення переліків, і видаляє клон. Окрім інструментів з вимог, їй потрібно:

• jq, curl та openssl у вашому PATH
• доступ до мережі, щоб клонувати тег і завантажити Go-модулі та etcd
• вільні TCP-порти 2379 та 8050

Upstream-скрипт запускає etcd на порту 2379 і тимчасовий сервер API на порту 8050; встановіть ETCD_PORT або API_PORT, якщо якийсь із них зайнятий. Він завантажує власну копію etcd і збирає kube-apiserver, тому очікуйте, що перший запуск триватиме кілька хвилин.

Щоб зберегти тимчасовий клон і журнал генерації для усунення несправностей:

KEEP_TMP=1 make updateapispec-enums-from-source

Варіант 2: Копіювання закоміченої специфікації з локального клону

Цей варіант потребує локальний клон kubernetes/kubernetes і копіює специфікацію набагато швидше.

У вашому клоні kubernetes/kubernetes виконайте hack/update-openapi-spec.sh і збрежіть перегенерований api/openapi-spec/swagger.json у тезі v$K8S_RELEASE. Потім скопіюйте його у reference-docs:

export K8S_ROOT=<your-path-to>/kubernetes
cd <rdocs-base>
make updateapispec

Ціль читає файл так, як він збережений в цьому тезі, а не файл у вашому робочому дереві. Це єдиний крок на цій сторінці, який читає K8S_ROOT.

Перевірка специфікації

Який би варіант ви не використали, ви можете перевірити специфікацію на наявність значень переліків у будь-який час:

./hack/verify-enum-swagger.sh gen-apidocs/config/<version>/swagger.json

Запуск локального попереднього перегляду

Запустіть попередній перегляд один раз, у другому терміналі, і залиште його працювати. Hugo перезавантажує кожну сторінку, коли цілі копіювання замінюють її, тому ви можете перевіряти кожен набір довідки одразу після його генерації.

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

Hugo надає попередній перегляд у http://localhost:1313/.

Генерація довідки API Kubernetes

gen-apidocs збирає цей набір (HTML-довідку API) зі специфікації OpenAPI, яку ви отримали. Результат збірки йде до gen-apidocs/build/html/, перш ніж ціль скопіює його.

cd <rdocs-base>
make copyapi

Ціль записує два файли у <web-base>:

static/docs/reference/generated/kubernetes-api/v1.38/index.html
static/docs/reference/generated/kubernetes-api/v1.38/js/navData.js

Перевірте /docs/reference/generated/kubernetes-api/v1.38/ у попередньому перегляді. Відкрийте такий ресурс, як Pod, і пошукайте на сторінці Possible enum values ("можливі значення переліків"), що підтверджує, що специфікація пронесла значення переліків крізь генерацію.

Дивіться Pull request-и для того, що відкрити для цього набору.

Генерація довідкових сторінок API у Markdown

gen-apidocs також збирає цей набір (довідку API у Markdown, яку Hugo відображає як звичайні сторінки) з тієї ж специфікації. Результат збірки йде до gen-apidocs/build/markdown/.

cd <rdocs-base>
make copyapimd

Ціль замінює <web-base>/content/en/docs/reference/kubernetes-api/ та зберігає _index.md, який люди підтримують вручну.

Перевірте /docs/reference/kubernetes-api/ у попередньому перегляді. Порівняйте кількість згенерованих сторінок з попереднім релізом:

find <web-base>/content/en/docs/reference/kubernetes-api -name '*.md' | wc -l

Дивіться Pull request-и для того, що відкрити для цього набору.

Генерація довідки компонентів

gen-compdocs збирає з k8s.io/kubernetes та з staging-модулів k8s.io, які go.mod закріплює директивами replace. go get оновлює перший і залишає решту, тому переміщуйте весь набір одразу:

cd <rdocs-base>/gen-compdocs
STAGING=v0.${K8S_RELEASE#*.}
go get k8s.io/kubernetes@v$K8S_RELEASE
KK=$(go list -m -f '{{.Dir}}' k8s.io/kubernetes)

# кожен staging-модуль цього релізу
for m in $(awk '/=> \.\/staging\/src\//{print $1}' "$KK/go.mod"); do
  go mod edit -replace="$m=$m@$STAGING" -require="$m@$STAGING"
done

# записи, що залишились від релізу з іншим набором staging-модулів
for m in $(go mod edit -json | jq -r '.Replace[].Old.Path'); do
  grep -q "$m => ./staging/src/$m" "$KK/go.mod" ||
    go mod edit -dropreplace="$m" -droprequire="$m"
done

go mod tidy
go mod edit -go=$(go list -m -f '{{.GoVersion}}' k8s.io/kubernetes)
go mod tidy

git ls-remote --tags https://github.com/kubernetes/api.git "v0.${K8S_RELEASE#*.}"

Цикли читають набір модулів з kubernetes/kubernetes, оскільки релізи додають і видаляють staging-модулі, і go.mod може все ще перелічувати модулі від старішого релізу. Директива go йде останньою: поки старі модулі ще у графі, go mod tidy піднімає її знову.

Перевірте, що змінилося:

git diff go.mod

Кожна вимога k8s.io, кожен replace і директива go тепер мають вказувати новий реліз. Вимоги поза staging-набором, такі як k8s.io/klog/v2 та пакети Goldmark, зберігають власні версії.

Потім зберіть і скопіюйте основні сторінки компонентів:

cd <rdocs-base>
make copycomp-core

gen-compdocs записує кожну сторінку компонента до gen-compdocs/build/, і ціль копіює kube-apiserver.md, kube-controller-manager.md, kube-scheduler.md, kube-proxy.md та kubelet.md звідти до <web-base>/content/en/docs/reference/command-line-tools-reference/.

Перевірте /docs/reference/command-line-tools-reference/ у попередньому перегляді.

Дивіться Pull request-и для того, що відкрити для цього набору.

Генерація довідки kubectl

Сторінки kubectl походять з тієї ж збірки gen-compdocs, що й довідка компонентів, і належать до власного pull request-а.

cd <rdocs-base>
make copycomp-kubectl

Ціль записує kubectl.md і теку для кожної підкоманди до <web-base>/content/en/docs/reference/kubectl/generated/ та зберігає _index.md, який люди підтримують вручну.

Перевірте /docs/reference/kubectl/generated/ у попередньому перегляді та відкрийте сторінку підкоманди, наприклад kubectl apply.

Дивіться Pull request-и для того, що відкрити для цього набору.

Генерація довідки kubeadm

Сторінки kubeadm також походять з gen-compdocs і належать до власного pull request-а.

cd <rdocs-base>
make copycomp-kubeadm

Ціль записує kubeadm.md і теку для кожної підкоманди до <web-base>/content/en/docs/reference/setup-tools/kubeadm/generated/ та зберігає _index.md і README.md, які люди підтримують вручну.

Перевірте /docs/reference/setup-tools/kubeadm/generated/ у попередньому перегляді.

Дивіться Pull request-и для того, що відкрити для цього набору.

Генерація довідки конфігураційних API

genref читає Go-типи конфігурацій кожного компонента з staging-модулів k8s.io. Він не має директив replace, тому самі вимоги вирішують, який реліз ви документуєте:

cd <rdocs-base>/genref
STAGING=v0.${K8S_RELEASE#*.}
OLD=$(go mod edit -json | jq -r '.Require[] | select(.Path=="k8s.io/api") | .Version')

# кожен модуль k8s.io, закріплений за попереднім релізом
go get $(go mod edit -json | jq -r --arg v "$OLD" --arg s "$STAGING" \
  '.Require[] | select(.Version==$v and (.Path|startswith("k8s.io/"))) | .Path + "@" + $s')

go mod tidy
go mod edit -go=$(go list -m -f '{{.GoVersion}}' k8s.io/api)
go mod tidy

Вибір за старою версією підбирає staging-модулі та залишає k8s.io/klog/v2, k8s.io/gengo та інші незалежні репозиторії у спокої. Перевірте, що змінилося:

git diff go.mod

Також оновіть реліз у цільовому посиланні externalPackages у genref/config.yaml, яке вказує читачам на опубліковану довідку API.

Перевірка на наявність нових версій API

genref генерує одну сторінку для кожного запису у genref/config.yaml, і кожен запис називає Go-пакет і шлях, що закінчується версією API:

  - name: kubelet-config
    title: Kubelet Configuration (v1)
    package: k8s.io/kubelet
    path: config/v1

Компонент, який починає обслуговувати нову версію свого конфігураційного API, додає теку версії у свій Go-вихідний код. Перелічіть теки версій компонента, щоб побачити, що існує у цьому релізі:

cd <rdocs-base>/genref
go mod download
ls "$(go list -m -f '{{.Dir}}' k8s.io/kubelet)/config"

Щоб порівняти кожен запис у config.yaml з вихідним кодом одразу, виконайте:

awk '$1=="package:"{pkg=$2} $1=="path:"{print pkg, $2}' config.yaml | sort -u |
while read -r pkg path; do
  dir=$(go list -m -f '{{.Dir}}' "$pkg" 2>/dev/null) || continue
  parent=$(dirname "$path")
  for v in $(find "$dir/$parent" -maxdepth 1 -mindepth 1 -type d -name 'v[0-9]*'); do
    grep -q "path: $parent/$(basename "$v")\$" config.yaml ||
      echo "$pkg $parent/$(basename "$v")"
  done
done | sort -u

Кожен рядок — це кандидат, а не прогалина, яку треба заповнити: кілька старіших версій навмисно пропущені, і коментарі у config.yaml фіксують чому. Додайте запис, коли компонент обслуговує версію, яку читачі налаштовують, і зберігайте запис для старішої версії, поки компонент все ще обслуговує її.

Збірка та копіювання сторінок

cd <rdocs-base>
make copyconfigapi

genref записує згенеровані сторінки до genref/output/md/, і ціль сортує їх під час копіювання: більшість іде до content/en/docs/reference/config-api/, метричні API йдуть до content/en/docs/reference/external-api/, оскільки проєкт визначає їх, але не обслуговує їх з сервера API, а сторінки, які вебсайт не публікує, пропускаються.

Перевірте обидва розділи у попередньому перегляді та підтвердіть, що жодна сторінка, яку ви опублікували для попереднього релізу, не зникла:

cd <web-base>
git status content/en/docs/reference/config-api/ content/en/docs/reference/external-api/

Дивіться Pull request-и для того, що відкрити для цього набору.

Підсумок

Кожна ціль копіювання спочатку збирає. Щоб зібрати кожен набір без копіювання чогось у ваш клон вебсайту, виконайте make api apimd comp configapi.

Pull request-и

Спочатку виконується збірка кожного об’єкта копіювання. Щоб зібрати всі набори, не копіюючи нічого у клон вашого вебсайту, виконайте команду make api apimd comp configapi.

У кожному pull request-і до вебсайту опишіть, як ви згенерували результат, щоб рецензент міг його відтворити:

Regenerated the kubectl reference for v1.38.0.

- Generated with `make copycomp-kubectl` from kubernetes-sigs/reference-docs at commit <commit>
- Generator changes: kubernetes-sigs/reference-docs#<pull request>
- Generated files only, with no hand edits

Для двох наборів довідки API додайте, як ви створили специфікацію OpenAPI, оскільки згенерований результат її не показує: generated from source with OpenAPIEnums=true або скопійована з клону.

Що далі

• Генерація довідкової документації для API Kubernetes
• Генерація довідкової документації для конфігураційних API
• Генерація довідкових сторінок для компонентів та інструментів Kubernetes
• Генерація довідкової документації для команд kubectl
• Генерація довідкової документації для метрик
• Внесення змін в upstream-код Kubernetes
• Інструкція для ролі з документації у kubernetes/sig-release

3 - Внесок у код Kubernetes

Ця сторінка показує, як зробити внесок у проєкт kubernetes/kubernetes. Ви можете виправити помилки, знайдені в документації API Kubernetes або вмісті компонентів Kubernetes, таких як kubeadm, kube-apiserver та kube-controller-manager.

Якщо ви хочете відновити довідкову документацію для API Kubernetes або компонентів kube-* з коду upstream, перегляньте наступні інструкції:

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

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

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

  • Git
  • Golang версії 1.13+
  • Docker
  • etcd
  • make
  • gcc compiler/linker

• Ваша змінна середовища GOPATH повинна бути встановлена, а розташування etcd повинно бути у вашій змінній середовища PATH.

• Вам потрібно знати, як створити pull request у репозиторій GitHub. Зазвичай це включає створення форку репозиторію. Для отримання додаткової інформації дивіться Створення Pull Request та Стандартний Workflow Fork & Pull Request на GitHub.

Загальна картина

Довідкова документація для API Kubernetes та компонентів kube-*, таких як kube-apiserver, kube-controller-manager, автоматично генерується з вихідного коду в upstream Kubernetes.

Коли ви бачите помилки в згенерованій документації, ви можете розглянути можливість створення патчу для виправлення помилки в upstream проєкті.

Клонування репозиторію Kubernetes

Якщо ви ще не маєте репозиторію kubernetes/kubernetes, отримайте його зараз:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Визначте базову теку вашого клону репозиторію kubernetes/kubernetes. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — $GOPATH/src/github.com/kubernetes/kubernetes. Наступні кроки посилаються на вашу базову теку як <k8s-base>.

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

Редагування вихідного коду Kubernetes

Довідкова документація API Kubernetes автоматично генерується з OpenAPI специфікації, яка створюється з вихідного коду Kubernetes. Якщо ви хочете змінити довідкову документацію API, перший крок — змінити один або кілька коментарів у вихідному коді Kubernetes.

Документація для компонентів kube-* також генерується з вихідного коду upstream. Ви повинні змінити код, повʼязаний з компонентом, який ви хочете виправити, щоб виправити згенеровану документацію.

Зробіть зміни у вихідному коді upstream

Ось приклад редагування коментаря у вихідному коді Kubernetes.

У вашому локальному репозиторії kubernetes/kubernetes, перейдіть на основну гілку і переконайтеся, що вона оновлена:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Припустимо, що у цьому вихідному файлі в основній гілці є помилка "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

У вашому локальному середовищі відкрийте types.go і змініть "atmost" на "at most".

Перевірте, що ви змінили файл:

git status

Вивід показує, що ви в основній гілці та що вихідний файл types.go був змінений:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Збережіть відредагований файл

Виконайте git add і git commit, щоб зберегти зміни, які ви внесли до цього моменту. У наступному кроці ви зробите другий коміт. Важливо зберігати ваші зміни в окремих комітах.

Генерація OpenAPI специфікації та супутніх файлів

Перейдіть до <k8s-base> і запустіть ці скрипти:

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Виконайте git status, щоб побачити, що було згенеровано.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Перегляньте вміст api/openapi-spec/swagger.json, щоб переконатися, що помилка виправлена. Наприклад, ви можете виконати git diff -a api/openapi-spec/swagger.json. Це важливо, оскільки swagger.json є вхідними даними для другого етапу процесу генерації документації.

Виконайте git add і git commit, щоб зберегти ваші зміни. Тепер у вас є два коміти: один з відредагованим файлом types.go, і один, що містить згенеровану OpenAPI специфікацію та супутні файли. Залишить ці два коміти окремо. Тобто, не зливайте ваші коміти.

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

PR 57758 є прикладом pull request, який виправляє помилку в коді Kubernetes.

Cherry-pick вашого коміту у релізну гілку

У попередньому розділі ви відредагували файл в основній гілці та потім запустили скрипти для генерації OpenAPI специфікації та супутніх файлів. Потім ви подали свої зміни у pull request до основної гілки репозиторію kubernetes/kubernetes. Тепер припустимо, що ви хочете повернути вашу зміну в релізну гілку. Наприклад, якщо основна гілка використовується для розробки версії Kubernetes 1.37, і ви хочете повернути вашу зміну у гілку release-1.36.

Згадайте, що ваш pull request має два коміти: один для редагування types.go і один для файлів, згенерованих скриптами. Наступний крок — запропонувати cherry pick вашого першого коміту у гілку release-1.36. Ідея полягає в тому, щоб зробити cherry-pick коміту, що редагував types.go, але не коміту, що має результати запуску скриптів. Для інструкцій дивіться Запропонувати Cherry Pick.

Коли у вас є pull request для cherry-pick вашого коміту у гілку release-1.36, наступний крок — запустити ці скрипти в гілці release-1.36 у вашому локальному середовищі.

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Тепер додайте коміт до вашого cherry-pick pull request, що містить нещодавно згенеровану OpenAPI специфікацію та супутні файли. Слідкуйте за вашим pull request, поки він не буде злитий у гілку release-1.36.

На цьому етапі й основна гілка, й гілка release-1.36 містять ваш оновлений файл types.go та набір згенерованих файлів, що відображають зміну, яку ви внесли в types.go. Зазначте, що згенерована OpenAPI специфікація та інші згенеровані файли в гілці release-1.36 не обовʼязково будуть такими ж, як згенеровані файли в основній гілці. Згенеровані файли в гілці release-1.36 містять API елементи лише з Kubernetes 1.36. Згенеровані файли в основній гілці можуть містити API елементи, які не є в 1.36, але розробляються для 1.37.

Генерація опублікованих довідкових документів

Попередній розділ показав, як редагувати вихідний файл і потім згенерувати декілька файлів, включаючи api/openapi-spec/swagger.json у репозиторії kubernetes/kubernetes. Файл swagger.json є файлом визначення OpenAPI, який використовується для генерації документації API.

Тепер ви готові слідувати посібнику Генерація довідкової документації для API Kubernetes, щоб згенерувати опубліковану довідкову документацію API Kubernetes.

Що далі

• Генерація довідкової документації для API Kubernetes
• Генерація довідкових документів для компонентів і інструментів Kubernetes
• Генерація довідкової документації для команд kubectl

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

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

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

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

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

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

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

• Вам потрібно знати, як створити 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.37/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.37/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.37/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.37/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.37/index.html
static/docs/reference/generated/kubernetes-api/v1.37/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.37/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.37/js/scroll.js

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

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

Локальне тестування документації 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 до його злиття.

Що далі

• Швидкий старт з генерації документації
• Генерація документації для компонентів та інструментів Kubernetes
• Генерація документації для команд kubectl

5 - Генерування довідкової документації для Configuration API

На цій сторінці показано, як можна створити оновлену довідкову документацію для Configuration API Kubernetes. Вона призначена для людей, які роблять внесок у Kubernetes.

Довідка з Configuration API документує формати конфігурації для інструментів та компонентів Kubernetes — наприклад, формати kubelet, kube-apiserver, kube-scheduler, kubeconfig та kubeadm. Опублікована довідка знаходиться за адресою /docs/reference/config-api/.

genref у kubernetes-sigs/reference-docs є генератором, який будує цю довідку. Він читає типи конфігурації Go кожного компонента та рендерить їх у вигляді Markdown.

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

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

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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

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

Вам знадобляться локальні клони kubernetes/website та kubernetes-sigs/reference-docs.

Якщо ви ще не зробили форк та клон kubernetes/website, перегляньте розділ Робота з локальним клоном. Клонуйте reference-docs:

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

Наступні кроки посилаються на ваш клон kubernetes/website як <web-base>, а ваш клон reference-docs як <rdocs-base>.

Встановлення змінних збирання

Встановіть це у вашій оболонці. Це застосовується до кожної команди make у кроках, що йдуть далі, незалежно від того, з якої теки ви її запускаєте.

export K8S_WEBROOT=/шлях/до/вашого/website   # ваш клон website (<web-base>)

Збирання та публікація довідки Configuration API

З <rdocs-base>:

cd <rdocs-base>
make copyconfigapi

Ця команда виконується у два етапи:

1. configapi — будує та запускає genref, який генерує Markdown у genref/output/md
2. copyconfigapi — копіює згенеровані файли у ваш клон website за адресою <web-base>/content/en/docs/reference/config-api/.

Перший запуск завантажує залежності модулів Go і може тривати кілька хвилин.

Перевірте, що змінилося у вашому клоні website:

cd <web-base>
git status

Шукайте оновлення, зроблені в content/en/docs/reference/config-api — наприклад:

content/en/docs/reference/config-api/kubelet-config.v1beta1.md
content/en/docs/reference/config-api/kubeadm-config.v1beta4.md
content/en/docs/reference/config-api/apiserver-config.v1.md
content/en/docs/reference/config-api/client-authentication.v1.md

Попередній перегляд website та локальне тестування

Перегляньте ваші оновлення:

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

Потім відкрийте локальний попередній перегляд у вашому вебоглядачі та підтвердьте, що сторінки, які ви оновили, завантажуються належним чином. Hugo показує цей локальний попередній перегляд за адресою http://localhost:1313/ Тож сторінка для перевірки — http://localhost:1313/docs/reference/config-api/

Збереження змін у коміті

Якщо ви повторно згенерували довідку з Configuration API для оновлення релізу, закомітьте змінені файли в content/en/docs/reference/config-api/ у <web-base>, потім відкрийте pull request у kubernetes/website.

Що далі

• Генерування довідкової документації для Kubernetes API
• Швидкий старт генерування довідкової документації
• Внесок до довідкової висхідної документації

6 - Генерація документації для команд kubectl

Ця сторінка показує, як згенерувати довідкову документацію для команд kubectl.

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

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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

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

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

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

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

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs

Якщо у вас ще немає репозиторію 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

Видаліть пакет spf13 з $GOPATH/src/k8s.io/kubernetes/vendor/github.com:

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

Репозиторій kubernetes/kubernetes надає вихідний код kubectl і kustomize.

• Визначте основну теку вашої копії репозиторію 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>.

У вашій локальній копії k8s.io/kubernetes перевірте гілку інтересу і переконайтеся, що вона актуальна. Наприклад, якщо ви хочете згенерувати документацію для Kubernetes 1.36.0, ви можете використати ці команди:

cd <k8s-base>
git checkout v1.36.0
git pull https://github.com/kubernetes/kubernetes 1.36.0

Якщо вам не потрібно редагувати вихідний код kubectl, дотримуйтесь інструкцій для Налаштування змінних для зборки.

Редагування вихідного коду kubectl

Документація довідки для команд kubectl автоматично генерується з вихідного коду kubectl. Якщо ви хочете змінити довідкову документацію, перший крок — змінити один або кілька коментарів у вихідному коді kubectl. Змініть їх у вашій локальній копії репозиторію kubernetes/kubernetes, а потім подайте pull request до основної гілки github.com/kubernetes/kubernetes.

PR 56673 є прикладом pull requestг, який виправляє помилку в вихідному коді kubectl.

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

Cherry pick вашої зміни до релізної гілки

Ваша зміна тепер знаходиться в основній гілці, яка використовується для розробки наступного випуску Kubernetes. Якщо ви хочете, щоб ваша зміна зʼявилася в документації для версії Kubernetes, яка вже була випущена, вам потрібно запропонувати, щоб вашу зміну було вибрано для релізної гілки.

Наприклад, припустимо, що основна гілка використовується для розробки Kubernetes 1.37 і ви хочете повернути вашу зміну до релізної гілки release-1.36. Для інструкцій про те, як це зробити, дивіться Пропонування вибірки.

Слідкуйте за вашим запитом на вибірку до його злиття в релізну гілку.

Налаштування змінних для збірки

Перейдіть до <rdocs-base>. У командному рядку встановіть наступні змінні середовища.

• Встановіть K8S_ROOT на <k8s-base>.
• Встановіть K8S_WEBROOT на <web-base>.
• Встановіть K8S_RELEASE на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.36, встановіть K8S_RELEASE на 1.36.

Наприклад:

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

Створення теки версії

Ціль збірки createversiondirs створює версійну теку і копіює конфігураційні файли довідки для kubectl до теки версії. Назва теки версії слідує шаблону v<major>_<minor>.

У теці <rdocs-base> виконайте наступну ціль зборки:

cd <rdocs-base>
make createversiondirs

Перевірте теґ релізу у k8s.io/kubernetes

У вашій локальній копії <k8s-base> перевірте гілку, яка містить версію Kubernetes, яку ви хочете задокументувати. Наприклад, якщо ви хочете згенерувати документацію для Kubernetes 1.36.0, перевірте теґ v1.36. Переконайтеся, що ваша локальна гілка актуальна.

cd <k8s-base>
git checkout v1.36.0
git pull https://github.com/kubernetes/kubernetes v1.36.0

Запустіть код генерації документації

У вашій локальній копії <rdocs-base>, виконайте ціль зборки copycli. Команда запускається як root:

cd <rdocs-base>
make copycli

Команда copycli очищує тимчасову теку збірки, генерує файли команд kubectl і копіює зведену HTML-сторінку довідки команд kubectl та активи до <web-base>.

Знайдіть згенеровані файли

Перевірте, чи ці два файли були згенеровані:

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

Знайдіть скопійовані файли

Перевірте, чи всі згенеровані файли були скопійовані до вашої <web-base> теки:

cd <web-base>
git status

Вивід має включати змінені файли:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

Вивід також може включати:

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

Локально протестуйте документацію

Побудуйте документацію Kubernetes у вашій локальній копії <web-base>.

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

Перегляньте локальний попередній перегляд.

Додайте та зафіксуйте зміни в kubernetes/website

Запустіть git add та git commit, щоб зафіксувати файли.

Створіть pull request

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

Через кілька хвилин після злиття вашого pull request оновлені теми довідки стануть видимими в опублікованій документації.

Що далі

• Швидкий старт генерування довідкової документації
• Генерація довідкової документації для компонентів і інструментів Kubernetes
• Генерація довідкової документації для API Kubernetes

7 - Генерація довідкової документації для метрик

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

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

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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

Клонування репозиторію Kubernetes

Генерація документації для метрик відбувається в репозиторії Kubernetes. Щоб клонувати репозиторій, перейдіть до теки, де ви хочете, щоб знаходилася клонована копія.

Потім виконайте наступну команду:

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

Це створить теку kubernetes у вашій поточній робочій теці.

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

У клонованому репозиторії Kubernetes знайдіть теку test/instrumentation/documentation. Документація для метрик генерується в цій теці.

З кожним релізом додаються нові метрики. Після того, як ви запустите скрипт генерації документації для метрик, скопіюйте документацію для метрик на вебсайт Kubernetes і опублікуйте оновлену документацію для метрик.

Щоб згенерувати останні метрики, переконайтеся, що ви знаходитесь в кореневій теці клонованого репозиторію Kubernetes. Потім виконайте наступну команду:

./test/instrumentation/update-documentation.sh

Щоб перевірити наявність змін, виконайте команду:

git status

Вивід буде схожий на:

./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml

Скопіюйте згенерований файл документації для метрик в репозиторій вебсайту Kubernetes

1. Встановіть змінну середовища для кореневої теки вебсайту Kubernetes.

   Виконайте наступну команду, щоб встановити кореневу теку вебсайту:

   export WEBSITE_ROOT=<шлях до кореня вебсайту>
   

2. Скопіюйте згенерований файл метрик в репозиторій вебсайту Kubernetes.

   cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
   

   Примітка:

   Якщо ви отримали помилку, перевірте, чи маєте ви дозволи на копіювання файлу. Ви можете використати chown, щоб змінити власника файлу на вашого користувача.

Створіть pull request

Щоб створити pull request, дотримуйтесь інструкцій у розділі Відкриття pull request.

Що далі

• Внесок у код Kubernetes
• Генерація довідкової документації для компонентів і інструментів Kubernetes
• Генерація довідкової документації для команд kubectl

8 - Генерація довідкових сторінок для компонентів та інструментів Kubernetes

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

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

Розпочніть з розділу Передумови у довідковому посібнику Quickstart для генерування документації.

Дотримуйтесь інструкцій у довідковому посібнику Quickstart, щоб згенерувати довідкові сторінки для компонентів та інструментів Kubernetes.

Що далі

• Довідковий посібник Quickstart для генерування документації
• Генерація довідкової документації для команд kubectl
• Генерація довідкової документації для API Kubernetes
• Внесення змін до проєкту Kubernetes для документації

9 -

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

  • Git
  • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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