This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Обзор справочной документации

Темы в этом разделе описывают, как генерировать справочные руководства Kubernetes.

Для сборки справочной документации посмотрите следующий ресурс:

1 - Участие в основном коде Kubernetes

На этой странице показано, как поучаствовать в основном содержимом проекта kubernetes/kubernetes. Вы можете исправить баги, найденные в документации по API Kubernetes или содержимом таких компонентов Kubernetes, как kubeadm, kube-apiserver и kube-controller-manager.

Если вместо этого вы хотите перегенерировать справочную документацию для API Kubernetes или компонентов с именем kube-* в основном коде, изучите следующие инструкции:

Подготовка к работе

Рассмотрение процесса в целом

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

Если вы заметили баги в сгенерированной документации, попробуйте его исправить через пулреквест в основной проект.

Клонирование репозитория 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-* также генерируется из основного исходного кода. Для изменения генерируемой документации вам нужно изменить соответствующий код компонента.

Внесение изменений в основной исходный код

Заметка: Следующие шаги служат примером, а не общим порядком действий. Детали могут отличаться в вашей ситуации.

Рассмотрим пример редактирования комментария в исходном коде Kubernetes.

В вашем локальном репозитории kubernetes/kubernetes переключитесь на ветку master и проверьте, что она актуальна:

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

Предположим, что в исходном файле в ветке master есть опечатка "atmost":

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

В вашем локальном окружении откройте types.go и измените "atmost" на "at most".

Убедитесь, что вы изменили файл:

git status

Вывод этой команды покажет, что вы находитесь в ветке master и был изменён исходный файл types.go:

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

Фиксация отредактированного файла

Выполните команду git add и git commit, чтобы зафиксировать внесенные вами изменения. На следующем шаге вы сделаете второй коммит. Следует отметить, что ваши изменения должны быть разделены на коммита.

Генерация спецификации OpenAPI и сопутствующих файлов

Перейдите в директорию <k8s-base> и выполните следующие скрипты:

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Выполните команду git status, чтобы посмотреть, какие файлы изменились.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    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 и сопутствующие файлы. Оформляйте эти изменения в виде двух отдельных коммитов. Это означает, что не нужно объединять коммиты.

Отправьте свои изменения как пулреквест в ветку master репозитория kubernetes/kubernetes. Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят.

PR 57758 — пример пулреквеста, который исправляет опечатку в исходном коде Kubernetes.

Заметка: Не всегда легко правильно определить, какой исходный файл нужно изменить. В предыдущем примере нужный исходный файл находится в директории staging в репозитории kubernetes/kubernetes. Однако в вашей ситуации файл для изменения может находится в другом месте, нежели чем в директории staging. Для получения помощи изучите файлы README в репозитории kubernetes/kubernetes и в смежных репозиториях, например, kubernetes/apiserver.

Применение вашего коммита в ветку выпуска

В предыдущем разделе вы отредактировали файл в ветке master, а затем запустили скрипты для генерации спецификации OpenAPI и смежных файлов. Затем вы отправили свои изменения в виде пулреквеста в ветку master репозитория kubernetes/kubernetes. Теперь представим, что вам нужно бэкпортировать изменения в ветку выпуска. К примеру, ветка master используется для разработки Kubernetes версии 1.10, а вы хотите применить ваши изменения в ветке release-1.9.

Напомним, что в вашем пулреквесте есть два коммита: первый для редактирования types.go, а второй — для файлов, сгенерированных скриптами. Следующий шаг — применить сделанный вами первый коммит в ветку release-1.9. Суть в том, чтобы выбрать коммит, который изменяет файл types.go, а не коммит с результатами выполнения скриптов. За инструкциями обратитесь к странице Propose a Cherry Pick.

Заметка: Применение коммита требует наличия возможности добавить метку и этап в вашем пулреквесте. Если у вас нет таких разрешений, вам нужно переговорить с кем-то, кто может сделать это для вас.

Когда в вашем пулреквесте есть определённый коммит, который нужно применить в ветке release-1.9, вам нужно запустить перечисленные ниже скрипты в этой вете из вашего локального окружения.

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Теперь зафиксируйте изменения в вашем пулреквесте с применённым коммитом, теперь там будет сгенерированная спецификация OpenAPI и связанные с ней файлы. Отслеживайте этот пулреквест до тех пор, пока он не будет объединен в ветке release-1.9.

Сейчас у вас и в ветке master, и в ветке release-1.9 есть обновленный файл types.go вместе с множеством сгенерированных файлов, в которых отражаются изменения, внесенные вами в types.go. Обратите внимание, что сгенерированная спецификация OpenAPI и другие сгенерированные файлы в ветке release-1.9 не обязательно совпадают с сгенерированными файлами в ветке master. Сгенерированные файлы в ветке release-1.9 содержат элементы API только из Kubernetes 1.9. Сгенерированные файлы в ветке master могут содержать элементы API не только для версии 1.9, но и для 1.10, которая ещё находится в разработке.

Генерация справочной документации

В предыдущем разделе было показано, как отредактировать исходный файл, а затем сгенерировать несколько файлов, включая api/openapi-spec/swagger.json в репозитории kubernetes/kubernetes. Файл swagger.json — это файл определения OpenAPI, который используется для генерации справочной документации API.

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

Что дальше

2 - Руководство по быстрому старту

На этой странице показано, как использовать скрипт update-imported-docs для генерации справочной документации Kubernetes. Скрипт автоматизирует настройку сборки и генерирует справочную документацию для выпуска.

Подготовка к работе

Требования:

  • Наличие компьютера под управлением ОС Linux или macOS.

  • Установленные следующие инструменты:

    • Python версии 3.7.x
    • Git
    • Golang версии 1.13+
    • Pip, который потребуется для установки PyYAML
    • PyYAML версии 5.1.2
    • make
    • gcc compiler/linker
    • Docker (требуется только для справочника команды kubectl)

  • В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

  • Вам нужно знать, как создать пулреквест в репозитории на GitHub. Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел Работа из локальной копии.

Получение репозитория документации

Убедитесь, что ваша копия репозитория website обновлена в соответствии с оригинальным репозиторием kubernetes/website, а затем склонируйте вашу копию website.

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

Определите базовую директорию вашей копии. Например, при выполнении предыдущего блока команд, то базовой директорией будет website. Далее в этом руководстве базовая директория в командах будет обозначаться <web-base>.

Заметка: Если вы хотите изменить контент инструментов компонента и справочник API, посмотрите руководство по участию в оригинальной документации.

Краткий обзор update-imported-docs

Скрипт update-imported-docs находится в директории <web-base>/update-imported-docs/.

Этот скрипт генерирует следующие справочники:

  • Справочные страницы для компонентов и инструментов
  • Справочник команды kubectl
  • API-справочник Kubernetes

Скрипт update-imported-docs генерирует справочную документацию 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 выполняет следующие шаги:

  1. Клонирует репозитории, указанные в конфигурационном файле. Для генерации справочной документации клонируемым репозиторием по умолчанию является kubernetes-sigs/reference-docs.
  2. Запускает команды в клонированных репозиториях для подготовки генератора документации, а затем генерирует файлы HTML и Markdown.
  3. Копирует сгенерированные файлы HTML и Markdown в локальную копию репозитория <web-base> в директории, указанные в конфигурационном файле.
  4. Обновляет ссылки на команды kubectl из kubectl.md, ссылаясь на разделы в справочнике по команде kubectl. . Когда сгенерированные файлы находятся в вашем локальной копии репозитория <web-base>, вы можете отправить их в виде пулреквеста в оригинальный репозиторий <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. В некоторых случаях изменения в исходном коде основного репозитория могут потребовать внесения изменений в конфигурационный файл (например, зависимости версий golang и изменения сторонних библиотек). Если у вас возникли проблемы со сборкой, обратитесь за помощью к команде SIG-Docs на канале #sig-docs в Slack Kubernetes.

Заметка: Команда 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

Вы можете запустить инструмент update-imported-docs следующим образом:

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

Например:

./update-imported-docs reference.yml 1.17

Исправление ссылок

Конфигурационный файл release.yml содержит инструкции по исправлению относительных ссылок Для исправления относительных ссылок в импортированных файлах, установите для свойство gen-absolute-links в значение true. В качестве примера можете посмотреть файл release.yml.

Внесение изменений в kubernetes/website

Список сгенерированных и скопированных файлов в <web-base> можно узнать, как показано ниже:

cd <web-base>
git status

В выводе команды будут показаны новые и измененные файлы. Полученный вывод может отличаться в зависимости от изменений основного исходного кода.

Сгенерированные файлы инструментом

content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
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

Сгенерированные файлы и директории для справочника API Kubernetes

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

Выполните git add и git commit, чтобы зафиксировать файлы в репозитории.

Создание пулреквеста

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят.

Спустя несколько минут после принятия вашего пулреквеста, обновленные темы справочника будут отображены в документации.

Что дальше

Для генерации отдельной взятой справочной документации путём ручной настройки необходимых репозиториев сборки и выполнении скриптов сборки обратитесь к следующим руководствам:

3 - Генерация справочной документации для API Kubernetes

На этой странице рассказывается про обновление справочной документации по API Kubernetes.

Справочная документация по API Kubernetes собирается из спецификации OpenAPI Kubernetes с использованием инструмента генерации kubernetes-sigs/reference-docs.

Если вы нашли баги в сгенерированной документации, то можете исправить их в основном коде.

Продолжайте чтение данной странице, если вы хотите перегенерировать справочную документацию из спецификации OpenAPI.

Подготовка к работе

Требования:

  • Наличие компьютера под управлением ОС Linux или macOS.

  • Установленные следующие инструменты:

    • Python версии 3.7.x
    • Git
    • Golang версии 1.13+
    • Pip, который потребуется для установки PyYAML
    • PyYAML версии 5.1.2
    • make
    • gcc compiler/linker
    • Docker (требуется только для справочника команды kubectl)

  • В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

  • Вам нужно знать, как создать пулреквест в репозитории на GitHub. Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел Работа из локальной копии.

Настройка локальных репозиториев

Создайте рабочую область и определите переменную окружения GOPATH.

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Загрузите локальные копии следующих репозиториев:

go get -u github.com/kubernetes-sigs/reference-docs

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 $GOPATH/src/github.com/<your-username>/website

Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

  • Определите базовую директорию вашей копии репозитория 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>.

Генерация справочной документации API

Далее в этом разделе рассматривается генерация справочной документации по API Kubernetes.

Настройка переменных для сборки

  • K8S_ROOT со значением <k8s-base>.
  • WEB_ROOT со значением <web-base>.
  • K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения K8S_RELEASE со значением 1.17.

Примеры:

export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17

Создание версионированной директории и получение Open API spec

Скрипт сборки 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/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/generators/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.17/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.17/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.17/index.html
static/docs/reference/generated/kubernetes-api/v1.17/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.17/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.17/js/scroll.js

Обновление указателя API-справочника

При генерации справочной документации для нового выпуска в файле <web-base>/content/en/docs/reference/kubernetes-api/api-index.md нужно прописать номер предстоящей версии.

  • Откройте файл <web-base>/content/en/docs/reference/kubernetes-api/api-index.md и обновите номер версии справочника API. Например:

    ---
title: v1.17
---

[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)

  • Откройте файл <web-base>/content/en/docs/reference/_index.md и добавьте ссылку на последний справочник API. Удалите самую старую версию справочника API. В этом файле должно быть 5 ссылок на новейшие API-справочники.

Тестирование справочника API локально

Соберите обновлённую версию API-справочника на своём компьютере. Проверьте ваши изменения на локальной предварительной версии сайта.

cd <web-base>
make docker-serve

Фиксация изменений

В директории <web-base> выполните команду git add и git commit для фиксации изменений в репозитории.

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят.

Отправьте свои изменения в виде пулреквеста в репозиторий kubernetes/kubernetes. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

Что дальше

4 - Генерация справочной документации для команд kubectl

На этой странице показано, как сгенерировать справочник для команды kubectl.

Заметка: На этой странице показывается, как сгенерировать справочную документацию для таких команд kubectl, как kubectl apply и kubectl taint. Этот раздел не рассматривает генерацию справочной страницы для опций kubectl. Инструкции по генерации справочной страницы опций kubectl смотрите в разделе Генерация справочной документации для компонентов и инструментов Kubernetes.

Подготовка к работе

Требования:

  • Наличие компьютера под управлением ОС Linux или macOS.

  • Установленные следующие инструменты:

    • Python версии 3.7.x
    • Git
    • Golang версии 1.13+
    • Pip, который потребуется для установки PyYAML
    • PyYAML версии 5.1.2
    • make
    • gcc compiler/linker
    • Docker (требуется только для справочника команды kubectl)

  • В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

  • Вам нужно знать, как создать пулреквест в репозитории на 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 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.17, вы можете использовать эти команды:

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

Если вам не нужно изменять исходный код kubectl, следуйте инструкциям по определению переменных сборки.

Редактирование исходного кода kubectl

Справочная документация по команде kubectl генерируется автоматически из исходного кода kubectl. Если вы хотите изменить справочную документацию, сначала измените один или несколько комментариев в исходном коде kubectl. Сделайте изменения в локальный репозиторий kubernetes/kubernetes, а затем отправьте пулреквест в ветку master репозитория github.com/kubernetes/kubernetes.

PR 56673 — пример пулреквеста, который исправляет опечатку в исходном коде kubectl.

Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят в ветку master репозитория kubernetes/kubernetes.

Применение вашего изменения в ветку выпуска

Теперь ваше изменение в ветке master, которая используется для разработки следующего выпуска Kubernetes. Если вы хотите добавить ваше изменение в документацию для уже выпущенной версии Kubernetes, вам нужно применить коммит с соответствующим изменением в нужную ветку выпуска.

Например, предположим, что ветка master используется для разработки Kubernetes 1.10, а вам нужно бэкпортировать ваше изменение в ветку release-1.15. За инструкциями обратитесь к странице Propose a Cherry Pick.

Отслеживайте ваш пулреквест с применённым изменением до тех пор, пока он не будет объединён в ветку выпуска.

Заметка: Применение коммита требует наличия возможности добавить метку и этап в вашем пулреквесте. Если у вас нет таких разрешений, вам нужно переговорить с кем-то, кто может сделать это для вас.

Настройка переменных для сборки

Перейдите на <rdocs-base>. В командной строке установите следующие переменные окружения.

  • K8S_ROOT со значением <k8s-base>.
  • WEB_ROOT со значением <web-base>.
  • K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения K8S_RELEASE со значением 1.17.

Примеры:

export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17

Создание версионированной директории

Скрипт сборки createversiondirs создаёт версионированную директорию и копирует туда конфигурационные файлы справочника kubectl. Имя версионированной директории имеет следующий вид: v<major>_<minor>.

В директории <rdocs-base> выполнение следующий скрипт сборки:

cd <rdocs-base>
make createversiondirs

Переход в тег выпуска в k8s.io/kubernetes

В вашем локальном репозитории <k8s-base> перейдите в ветку с версией Kubernetes, для которой вы хотите получить документацию. Например, если вы хотите сгенерировать документацию для Kubernetes 1.17, перейдите в тег v1.17.0. Убедитесь, что ваша локальная ветка содержит актуальные изменения.

cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.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>
make docker-serve

Посмотрите локальную предварительную версию сайта.

Добавление и фиксация изменений в kubernetes/website

Выполните команду git add и git commit для фиксации файлов.

Создание пулреквеста

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

Спустя несколько минут после принятия вашего пулреквеста, обновленные темы справочника будут отображены в документации.

Что дальше

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

На этой странице показывается, как собирать справочные страницы компонентов и инструментов Kubernetes.

Подготовка к работе

Начните с раздела с требованиями в руководстве по быстрому старту.

Для генерации справочных страниц компонентов и инструментов Kubernetes изучите страницу руководство по быстрому старту в справочной документации.

Что дальше