Ця сторінка показує, як використовувати скрипт update-imported-docs.py для генерації довідкової документації Kubernetes. Скрипт автоматизує налаштування збірки та генерує довідкову документацію для релізу.
Вам потрібна машина, що працює під управлінням Linux або macOS.
Вам потрібно встановити ці інструменти:
Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.
Вам потрібно знати, як створити 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.py розташований у теці <web-base>/update-imported-docs/.
Скрипт будує наступні довідки:
kubectlkubelet не генерується цим скриптом і підтримується вручну. Щоб оновити довідку kubelet, дотримуйтесь стандартного процесу внесення змін, описаного в Відкриття pull request.Скрипт update-imported-docs.py генерує довідкову документацію Kubernetes з вихідного коду Kubernetes. Скрипт створює тимчасову теку в /tmp на вашій машині та клонує потрібні репозиторії: kubernetes/kubernetes та kubernetes-sigs/reference-docs у цю теку. Скрипт встановлює вашу змінну середовища GOPATH на цю тимчасову теку. Встановлюються три додаткові змінні середовища:
K8S_RELEASEK8S_ROOTK8S_WEBROOTСкрипт потребує два аргументи для успішного виконання:
reference.yml)1.17Конфігураційний файл містить поле generate-command. Поле generate-command визначає серію інструкцій для збірки з kubernetes-sigs/reference-docs/Makefile. Змінна K8S_RELEASE визначає версію релізу.
Скрипт update-imported-docs.py виконує наступні кроки:
kubernetes-sigs/reference-docs.<web-base> за вказаними в конфігураційному файлі шляхами.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 документи, імпортовані за допомогою інструмента, повинні відповідати Посібнику зі стилю документації.
Відкрийте <web-base>/update-imported-docs/reference.yml для редагування. Не змінюйте вміст поля generate-command, якщо не розумієте, як команда використовується для побудови довідок. Оновлення reference.yml зазвичай не потрібне. Іноді зміни в upstream вихідному коді можуть вимагати змін у конфігураційному файлі (наприклад: залежності версій golang та зміни сторонніх бібліотек). Якщо ви стикаєтеся з проблемами збірки, зверніться до команди SIG-Docs у #sig-docs Kubernetes Slack.
generate-command є необовʼязковим полем, яке можна використовувати для запуску заданої команди або короткого скрипту для генерації документації з репозиторію.У 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.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.
Перегляньте файли, що були згенеровані та скопійовані до <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
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
static/docs/reference/generated/kubernetes-api/v1.35/index.html
static/docs/reference/generated/kubernetes-api/v1.35/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.35/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.35/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.35/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.35/css/bootstrap.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
Виконайте git add та git commit, щоб зафіксувати файли.
Створіть pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.
Через кілька хвилин після злиття вашого pull request, ваша оновлена довідкова документація буде видна в опублікованій документації.
Щоб згенерувати окрему довідкову документацію, вручну налаштувавши необхідні репозиторії та запустивши цільові завдання збірки, дивіться наступні посібники: