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

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

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

Вимоги:

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

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

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

  • Вам потрібно знати, як створити 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.31.0, ви можете використати ці команди:

cd <k8s-base>
git checkout v1.31.0
git pull https://github.com/kubernetes/kubernetes 1.31.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.32 і ви хочете повернути вашу зміну до релізної гілки release-1.31. Для інструкцій про те, як це зробити, дивіться Пропонування вибірки.

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

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

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

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

Наприклад:

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

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

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

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

cd <rdocs-base>
make createversiondirs

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

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

cd <k8s-base>
git checkout v1.31.0
git pull https://github.com/kubernetes/kubernetes v1.31.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 оновлені теми довідки стануть видимими в опублікованій документації.

Що далі

Змінено August 10, 2024 at 8:09 PM PST: Local links were prefixed with "uk" (7d9a96f799)