Ця сторінка показує, як згенерувати довідкову документацію для команд 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.34.0, ви можете використати ці команди:
cd <k8s-base>
git checkout v1.34.0
git pull https://github.com/kubernetes/kubernetes 1.34.0
Якщо вам не потрібно редагувати вихідний код kubectl, дотримуйтесь інструкцій для Налаштування змінних для зборки.
Документація довідки для команд kubectl автоматично генерується з вихідного коду kubectl. Якщо ви хочете змінити довідкову документацію, перший крок — змінити один або кілька коментарів у вихідному коді kubectl. Змініть їх у вашій локальній копії репозиторію kubernetes/kubernetes, а потім подайте pull request до основної гілки github.com/kubernetes/kubernetes.
PR 56673 є прикладом pull requestг, який виправляє помилку в вихідному коді kubectl.
Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів. Продовжуйте слідкувати за вашим pull request до його злиття в цільову гілку репозиторію kubernetes/kubernetes.
Ваша зміна тепер знаходиться в основній гілці, яка використовується для розробки наступного випуску Kubernetes. Якщо ви хочете, щоб ваша зміна зʼявилася в документації для версії Kubernetes, яка вже була випущена, вам потрібно запропонувати, щоб вашу зміну було вибрано для релізної гілки.
Наприклад, припустимо, що основна гілка використовується для розробки Kubernetes 1.35 і ви хочете повернути вашу зміну до релізної гілки release-1.34. Для інструкцій про те, як це зробити, дивіться Пропонування вибірки.
Слідкуйте за вашим запитом на вибірку до його злиття в релізну гілку.
Перейдіть до <rdocs-base>. У командному рядку встановіть наступні змінні середовища.
K8S_ROOT на <k8s-base>.K8S_WEBROOT на <web-base>.K8S_RELEASE на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.34, встановіть K8S_RELEASE на 1.34.Наприклад:
export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.34
Ціль збірки createversiondirs створює версійну теку і копіює конфігураційні файли довідки для kubectl до теки версії. Назва теки версії слідує шаблону v<major>_<minor>.
У теці <rdocs-base> виконайте наступну ціль зборки:
cd <rdocs-base>
make createversiondirs
У вашій локальній копії <k8s-base> перевірте гілку, яка містить версію Kubernetes, яку ви хочете задокументувати. Наприклад, якщо ви хочете згенерувати документацію для Kubernetes 1.34.0, перевірте теґ v1.34. Переконайтеся, що ваша локальна гілка актуальна.
cd <k8s-base>
git checkout v1.34.0
git pull https://github.com/kubernetes/kubernetes v1.34.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
Перегляньте локальний попередній перегляд.
Запустіть git add та git commit, щоб зафіксувати файли.
Створіть pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.
Через кілька хвилин після злиття вашого pull request оновлені теми довідки стануть видимими в опублікованій документації.