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

На этой странице показано, как использовать скрипт 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. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят.

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

Что дальше

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

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