Ця сторінка демонструє, як оновити документацію 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 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
Ціль збірки updateapispec створює теку версії для збірки. Після створення теки, специфікація Open API завантажується з репозиторію <k8s-base>. Ці кроки забезпечують відповідність версій конфігураційних файлів і Kubernetes Open API специфікації з версією релізу. Назва теки версії слідує шаблону v<major>_<minor>.
У теці <rdocs-base>, виконайте наступну ціль збірки:
cd <rdocs-base>
make updateapispec
Ціль 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 (версія HTML) копіюються в <web-base>/static/docs/reference/generated/kubernetes-api/v1.35/. Ця тека містить автономну документацію API у форматі HTML.
<web-base>/content/en/docs/reference/kubernetes-api/, генерується окремо за допомогою генератора gen-resourcesdocs.Опублікуйте локальну версію документації 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 до його злиття.