diff --git a/content/ru/docs/contribute/generate-ref-docs/_index.md b/content/ru/docs/contribute/generate-ref-docs/_index.md new file mode 100644 index 0000000000..ac25aa014c --- /dev/null +++ b/content/ru/docs/contribute/generate-ref-docs/_index.md @@ -0,0 +1,11 @@ +--- +title: Обзор справочной документации +main_menu: true +weight: 80 +--- + +Темы в этом разделе описывают, как генерировать справочные руководства Kubernetes. + +Для сборки справочной документации посмотрите следующий ресурс: + +* [Краткое руководство по генерации справочной документации](/docs/contribute/generate-ref-docs/quickstart/) diff --git a/content/ru/docs/contribute/generate-ref-docs/contribute-upstream.md b/content/ru/docs/contribute/generate-ref-docs/contribute-upstream.md new file mode 100644 index 0000000000..07fe564753 --- /dev/null +++ b/content/ru/docs/contribute/generate-ref-docs/contribute-upstream.md @@ -0,0 +1,185 @@ +--- +title: Участие в основном коде Kubernetes +content_template: templates/task +weight: 20 +--- + +{{% capture overview %}} + +На этой странице показано, как поучаствовать в основном содержимом проекта `kubernetes/kubernetes`. +Вы можете исправить баги, найденные в документации по API Kubernetes или содержимом таких компонентов Kubernetes, как `kubeadm`, `kube-apiserver` и `kube-controller-manager`. + +Если вместо этого вы хотите перегенерировать справочную документацию для API Kubernetes или компонентов с именем `kube-*` в основном коде, изучите следующие инструкции: + +- [Генерация справочной документации для API Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-api/) +- [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/) + +{{% /capture %}} + +{{% capture prerequisites %}} + +- Установленные инструменты: + + - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - [Golang](https://golang.org/doc/install) версии 1.13+ + - [Docker](https://docs.docker.com/engine/installation/) + - [etcd](https://github.com/coreos/etcd/) + +- Созданная переменная окружения `GOPATH`, а путь к `etcd` должен быть прописан в переменной окружения `PATH`. + +- Вам необходимо знать, как создать пулреквест в репозитории на GitHub. + Это обычно предполагает создание копии репозитория. + Для получения дополнительной информации смотрите страницы [Создание пулреквеста](https://help.github.com/articles/creating-a-pull-request/) и [Стандартный рабочий процесс в GitHub по работе с копией и пулреквестом](https://gist.github.com/Chaser324/ce0505fbed06b947d962). + +{{% /capture %}} + +{{% capture steps %}} + +## Рассмотрение процесса в целом + +Справочная документация для API Kubernetes и таких компонентов с `kube-*`, как `kube-apiserver`, `kube-controller-manager`, автоматически генерируются из исходного кода в [основном репозитории Kubernetes](https://github.com/kubernetes/kubernetes/). + +Если вы заметили баги в сгенерированной документации, попробуйте его исправить через пулреквест в основной проект. + +## Клонирование репозитория Kubernetes + +Если вы ещё не склонировали репозиторий kubernetes/kubernetes, сделайте это: + +```shell +mkdir $GOPATH/src +cd $GOPATH/src +go get github.com/kubernetes/kubernetes +``` + +Определите базовую директорию вашей копии репозитория [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com/kubernetes/kubernetes`. +В остальных команд базовая директория будет именоваться как ``. + +Определите базовую директорию вашей копии репозитория [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs). Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`. +В остальных команд базовая директория будет именоваться как ``. + +## Редактирование исходного кода Kubernetes + +Справочная документация API Kubernetes генерируется автоматически из спецификации OpenAPI в исходном коде Kubernetes. Если вы хотите изменить справочную документацию API, сначала нужно изменить один или несколько комментариев в исходном коде Kubernetes. + +Документация для компонентов `kube-*` также генерируется из основного исходного кода. Для изменения генерируемой документации вам нужно изменить соответствующий код компонента. + +### Внесение изменений в основной исходный код + +{{< note >}} +Следующие шаги служат примером, а не общим порядком действий. Детали могут отличаться в вашей ситуации. +{{< /note >}} + +Рассмотрим пример редактирования комментария в исходном коде Kubernetes. + +В вашем локальном репозитории kubernetes/kubernetes переключитесь на ветку master и проверьте, что она актуальна: + +```shell +cd +git checkout master +git pull https://github.com/kubernetes/kubernetes master +``` + +Предположим, что в исходном файле в ветке master есть опечатка "atmost": + +[kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/apps/v1/types.go) + +В вашем локальном окружении откройте `types.go` и измените "atmost" на "at most". + +Убедитесь, что вы изменили файл: + +```shell +git status +``` + +Вывод этой команды покажет, что вы находитесь в ветке master и был изменён исходный файл `types.go`: + +```shell +On branch master +... + modified: staging/src/k8s.io/api/apps/v1/types.go +``` + +### Фиксация отредактированного файла + +Выполните команду `git add` и `git commit`, чтобы зафиксировать внесенные вами изменения. На следующем шаге вы сделаете второй коммит. Следует отметить, что ваши изменения должны быть разделены на коммита. + +### Генерация спецификации OpenAPI и сопутствующих файлов + +Перейдите в директорию `` и выполните следующие скрипты: + +```shell +hack/update-generated-swagger-docs.sh +hack/update-openapi-spec.sh +hack/update-generated-protobuf.sh +hack/update-api-reference-docs.sh +``` + +Выполните команду `git status`, чтобы посмотреть, какие файлы изменились. + +```shell +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 и сопутствующие файлы. Оформляйте эти изменения в виде двух отдельных коммитов. Это означает, что не нужно объединять коммиты. + +Отправьте свои изменения как [пулреквест](https://help.github.com/articles/creating-a-pull-request/) в ветку master репозитория [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). +Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят. + +[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) — пример пулреквеста, который исправляет опечатку в исходном коде Kubernetes. + +{{< note >}} +Не всегда легко правильно определить, какой исходный файл нужно изменить. В предыдущем примере нужный исходный файл находится в директории `staging` в репозитории `kubernetes/kubernetes`. Однако в вашей ситуации файл для изменения может находится в другом месте, нежели чем в директории `staging`. Для получения помощи изучите файлы `README` в репозитории [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging) и в смежных репозиториях, например, [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md). +{{< /note >}} + +### Применение вашего коммита в ветку выпуска + +В предыдущем разделе вы отредактировали файл в ветке master, а затем запустили скрипты для генерации спецификации OpenAPI и смежных файлов. Затем вы отправили свои изменения в виде пулреквеста в ветку master репозитория kubernetes/kubernetes. Теперь представим, что вам нужно бэкпортировать изменения в ветку выпуска. К примеру, ветка master используется для разработки Kubernetes версии 1.10, а вы хотите применить ваши изменения в ветке release-1.9. + +Напомним, что в вашем пулреквесте есть два коммита: первый для редактирования `types.go`, а второй — для файлов, сгенерированных скриптами. Следующий шаг — применить сделанный вами первый коммит в ветку release-1.9. Суть в том, чтобы выбрать коммит, который изменяет файл `types.go`, а не коммит с результатами выполнения скриптов. За инструкциями обратитесь к странице [Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md). + +{{< note >}} +Применение коммита требует наличия возможности добавить метку и этап в вашем пулреквесте. Если у вас нет таких разрешений, вам нужно переговорить с кем-то, кто может сделать это для вас. +{{< /note >}} + +Когда в вашем пулреквесте есть определённый коммит, который нужно применить в ветке release-1.9, вам нужно запустить перечисленные ниже скрипты в этой вете из вашего локального окружения. + +```shell +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](/ru/docs/contribute/generate-ref-docs/kubernetes-api/), чтобы создать [справочную документацию API Kubernetes](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/). + +{{% /capture %}} + +{{% capture whatsnext %}} + +* [Генерация справочной документации для API Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-api/) +* [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/) +* [Генерация справочной документации для команд kubectl](/ru/docs/contribute/generate-ref-docs/kubectl/) + +{{% /capture %}} diff --git a/content/ru/docs/contribute/generate-ref-docs/kubectl.md b/content/ru/docs/contribute/generate-ref-docs/kubectl.md new file mode 100644 index 0000000000..df75084ab8 --- /dev/null +++ b/content/ru/docs/contribute/generate-ref-docs/kubectl.md @@ -0,0 +1,224 @@ +--- +title: Генерация справочной документации для команд kubectl +content_template: templates/task +weight: 90 +--- + +{{% capture overview %}} + +На этой странице показано, как сгенерировать справочник для команды `kubectl`. + +{{< note >}} +На этой странице показывается, как сгенерировать справочную документацию для таких [команд kubectl](/ru/docs/reference/generated/kubectl/kubectl-commands), как [kubectl apply](/ru/docs/reference/generated/kubectl/kubectl-commands#apply) и [kubectl taint](/ru/docs/reference/generated/kubectl/kubectl-commands#taint). +Этот раздел не рассматривает генерацию справочной страницы для опций [kubectl](/ru/docs/reference/generated/kubectl/kubectl/). Инструкции по генерации справочной страницы опций kubectl смотрите в разделе [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/). +{{< /note >}} + +{{% /capture %}} + +{{% capture prerequisites %}} + +{{< include "prerequisites-ref-docs.md" >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Настройка локальных репозиториев + +Создайте рабочую область и определите переменную окружения `GOPATH`. + +```shell +mkdir -p $HOME/ + +export GOPATH=$HOME/ +``` + +Загрузите локальные копии следующих репозиториев: + +```shell +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, клонируйте её на свой компьютер: + +```shell +git clone https://github.com//website $GOPATH/src/github.com//website +``` + +Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes: + +```shell +git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes +``` + +Удалите пакет spf13 в `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`. + +```shell +rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13 +``` + +В репозитории kubernetes/kubernetes использует исходный код `kubectl` и `kustomize`. + +* Определите базовую директорию вашей копии репозитория [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/k8s.io/kubernetes`. +В остальных командах базовая директория будет именоваться как ``. + +* Определите базовую директорию вашей копии репозитория [kubernetes/website](https://github.com/kubernetes/website). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com//website`. +В остальных команд базовая директория будет именоваться как ``. + +* Определите базовую директорию вашей копии репозитория [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`. +В остальных команд базовая директория будет именоваться как ``. + +В вашем локальном репозитории k8s.io/kubernetes переключитесь в нужную вам ветку и убедитесь, что она в актуальном состоянии. Например, если вам нужно сгенерировать документацию для Kubernetes 1.17, вы можете использовать эти команды: + +```shell +cd +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](https://github.com/kubernetes/kubernetes). + +[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) — пример пулреквеста, который исправляет опечатку в исходном коде kubectl. + +Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят в ветку master репозитория kubernetes/kubernetes. + +## Применение вашего изменения в ветку выпуска + +Теперь ваше изменение в ветке master, которая используется для разработки следующего выпуска Kubernetes. Если вы хотите добавить ваше изменение в документацию для уже выпущенной версии Kubernetes, вам нужно применить коммит с соответствующим изменением в нужную ветку выпуска. + +Например, предположим, что ветка master используется для разработки Kubernetes 1.10, а вам нужно бэкпортировать ваше изменение в ветку release-1.15. За инструкциями обратитесь к странице [Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md). + +Отслеживайте ваш пулреквест с применённым изменением до тех пор, пока он не будет объединён в ветку выпуска. + +{{< note >}} +Применение коммита требует наличия возможности добавить метку и этап в вашем пулреквесте. Если у вас нет таких разрешений, вам нужно переговорить с кем-то, кто может сделать это для вас. +{{< /note >}} + +## Настройка переменных для сборки + +Перейдите на ``. В командной строке установите следующие переменные окружения. + +* `K8S_ROOT` со значением ``. +* `WEB_ROOT` со значением ``. +* `K8S_RELEASE` со значением нужной версии документации. + Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения `K8S_RELEASE` со значением 1.17. + +Примеры: + +```shell +export WEB_ROOT=$(GOPATH)/src/github.com//website +export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes +export K8S_RELEASE=1.17 +``` + +## Создание версионированной директории + +Скрипт сборки `createversiondirs` создаёт версионированную директорию и копирует туда конфигурационные файлы справочника kubectl. +Имя версионированной директории имеет следующий вид: `v_`. + +В директории `` выполнение следующий скрипт сборки: + +```shell +cd +make createversiondirs +``` + +## Переход в тег выпуска в k8s.io/kubernetes + +В вашем локальном репозитории `` перейдите в ветку с версией Kubernetes, для которой вы хотите получить документацию. Например, если вы хотите сгенерировать документацию для Kubernetes 1.17, перейдите в тег `v1.17.0`. Убедитесь, что ваша локальная ветка содержит актуальные изменения. + +```shell +cd +git checkout v1.17.0 +git pull https://github.com/kubernetes/kubernetes v1.17.0 +``` + +## Выполнение кода для генерации документации + +В вашей локальной директории `` запустите скрипт сборки `copycli`. Команда выполняется от пользователя `root`: + +```shell +cd +make copycli +``` + +Команда `copycli` удаляет временную директорию сборки, генерирует файлы команды kubectl и копирует полученную HTML-страницу справочника команде kubectl и ресурсы в ``. + +## Проверка сгенерированных файлов + +Убедитесь в том, что перечисленные ниже два файлы были сгенерированы: + +```shell +[ -e "/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html" +[ -e "/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js" +``` + +## Проверка скопированных файлов + +Убедитесь в том, все сгенерированные файлы были скопированы в вашу директорию ``: + +```shell +cd +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 в вашей директории ``. + +```shell +cd +make docker-serve +``` + +Посмотрите [локальную предварительную версию сайта](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/). + +## Добавление и фиксация изменений в kubernetes/website + +Выполните команду `git add` и `git commit` для фиксации файлов. + +## Создание пулреквеста + +Создайте пулреквест в репозиторий `kubernetes/website`. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят. + +Спустя несколько минут после принятия вашего пулреквеста, обновленные темы справочника будут отображены в [документации](/ru/docs/home/). + +{{% /capture %}} + +{{% capture whatsnext %}} + +* [Руководство по быстрому старту генерации справочной документации](/ru/docs/contribute/generate-ref-docs/quickstart/) +* [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/) +* [Генерация справочной документации для API Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-api/) + +{{% /capture %}} diff --git a/content/ru/docs/contribute/generate-ref-docs/kubernetes-api.md b/content/ru/docs/contribute/generate-ref-docs/kubernetes-api.md new file mode 100644 index 0000000000..68f5ad1199 --- /dev/null +++ b/content/ru/docs/contribute/generate-ref-docs/kubernetes-api.md @@ -0,0 +1,188 @@ +--- +title: Генерация справочной документации для API Kubernetes +content_template: templates/task +weight: 50 +--- + +{{% capture overview %}} + +На этой странице рассказывается про обновление справочной документации по API Kubernetes. + +Справочная документация по API Kubernetes собирается из [спецификации OpenAPI Kubernetes](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json) с использованием инструмента генерации [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs). + +Если вы нашли баги в сгенерированной документации, то можете [исправить их в основном коде](/docs/contribute/generate-ref-docs/contribute-upstream/). + +Продолжайте чтение данной странице, если вы хотите перегенерировать справочную документацию из спецификации [OpenAPI](https://github.com/OAI/OpenAPI-Specification). + +{{% /capture %}} + +{{% capture prerequisites %}} + +{{< include "prerequisites-ref-docs.md" >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Настройка локальных репозиториев + +Создайте рабочую область и определите переменную окружения `GOPATH`. + +```shell +mkdir -p $HOME/ + +export GOPATH=$HOME/ +``` + +Загрузите локальные копии следующих репозиториев: + +```shell +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, клонируйте её на свой компьютер: + +```shell +git clone https://github.com//website $GOPATH/src/github.com//website +``` + +Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes: + +```shell +git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes +``` + +* Определите базовую директорию вашей копии репозитория [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/k8s.io/kubernetes`. +В остальных командах базовая директория будет именоваться как ``. + +* Определите базовую директорию вашей копии репозитория [kubernetes/website](https://github.com/kubernetes/website). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com//website`. +В остальных командах базовая директория будет именоваться как ``. + +* Определите базовую директорию вашей копии репозитория [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs). +Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`. +В остальных командах базовая директория будет именоваться как ``. + +## Генерация справочной документации API + +Далее в этом разделе рассматривается генерация [справочной документации по API Kubernetes](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/). + +### Настройка переменных для сборки + +* `K8S_ROOT` со значением ``. +* `WEB_ROOT` со значением ``. +* `K8S_RELEASE` со значением нужной версии документации. + Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения `K8S_RELEASE` со значением 1.17. + +Примеры: + +```shell +export WEB_ROOT=$(GOPATH)/src/github.com//website +export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes +export K8S_RELEASE=1.17 +``` + +### Создание версионированной директории и получение Open API spec + +Скрипт сборки `updateapispec` создает версионированную директорию для сборки. +После создания директории спецификация Open API генерируется из репозитория ``. Таким образом версия конфигурационных файлов и спецификация Kubernetes Open API будут совпадать с версией выпуска. +Имя версионированной директории имеет следующий вид: `v_`. + +В директории `` выполните следующий скрипт сборки: + +```shell +cd +make updateapispec +``` + +### Сборка справочной документации API + +Скрипт сборки `copyapi` создает справочник API и копирует генерированные файлы в каталоги в ``. +Выполните следующую команду в ``: + +```shell +cd +make copyapi +``` + +Убедитесь в том, что перечисленные ниже два файлы были сгенерированы: + +```shell +[ -e "/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html" +[ -e "/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js" +``` + +Перейдите в корень директории `` и посмотрите, какие файлы были изменены: + +```shell +cd +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-справочника + +При генерации справочной документации для нового выпуска в файле `/content/en/docs/reference/kubernetes-api/api-index.md` нужно прописать номер предстоящей версии. + +* Откройте файл `/content/en/docs/reference/kubernetes-api/api-index.md` и обновите номер версии справочника API. Например: + + ``` + --- + title: v1.17 + --- + + [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/) + ``` + +* Откройте файл `/content/en/docs/reference/_index.md` и добавьте ссылку на последний справочник API. Удалите самую старую версию справочника API. + В этом файле должно быть 5 ссылок на новейшие API-справочники. + +## Тестирование справочника API локально + +Соберите обновлённую версию API-справочника на своём компьютере. +Проверьте ваши изменения на [локальной предварительной версии сайта](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.17/). + +```shell +cd +make docker-serve +``` + +## Фиксация изменений + +В директории `` выполните команду `git add` и `git commit` для фиксации изменений в репозитории. + +Создайте пулреквест в репозиторий `kubernetes/website`. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят. + +Отправьте свои изменения в виде [пулреквеста](/ru/docs/contribute/start/) в репозиторий [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). +Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят. + +{{% /capture %}} + +{{% capture whatsnext %}} + +* [Руководство по быстрому старту генерации справочной документации](/ru/docs/contribute/generate-ref-docs/quickstart/) +* [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/) +* [Генерация справочной документации для команд kubectl](/ru/docs/contribute/generate-ref-docs/kubectl/) + +{{% /capture %}} diff --git a/content/ru/docs/contribute/generate-ref-docs/kubernetes-components.md b/content/ru/docs/contribute/generate-ref-docs/kubernetes-components.md new file mode 100644 index 0000000000..194a496574 --- /dev/null +++ b/content/ru/docs/contribute/generate-ref-docs/kubernetes-components.md @@ -0,0 +1,32 @@ +--- +title: Генерация справочных страниц для компонентов и инструментов Kubernetes +content_template: templates/task +weight: 120 +--- + +{{% capture overview %}} + +На этой странице показывается, как собирать справочные страницы компонентов и инструментов Kubernetes. + +{{% /capture %}} + +{{% capture prerequisites %}} + +Начните с [раздела с требованиями](/ru/docs/contribute/generate-ref-docs/quickstart/#подготовка-к-работе) в руководстве по быстрому старту. + +{{% /capture %}} + +{{% capture steps %}} + +Для генерации справочных страниц компонентов и инструментов Kubernetes изучите страницу [руководство по быстрому старту в справочной документации](/docs/contribute/generate-ref-docs/quickstart/). + +{{% /capture %}} + +{{% capture whatsnext %}} + +* [Краткое руководство по генерации справочной документации](/ru/docs/contribute/generate-ref-docs/quickstart/) +* [Генерация справочной документации для команд kubectl](/ru/docs/contribute/generate-ref-docs/kubectl/) +* [Генерация справочной документации для API Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-api/) +* [Участие в документации основного кода проекта Kubernetes](/ru/docs/contribute/generate-ref-docs/contribute-upstream/) + +{{% /capture %}} diff --git a/content/ru/docs/contribute/generate-ref-docs/quickstart.md b/content/ru/docs/contribute/generate-ref-docs/quickstart.md new file mode 100644 index 0000000000..8fce407be0 --- /dev/null +++ b/content/ru/docs/contribute/generate-ref-docs/quickstart.md @@ -0,0 +1,220 @@ +--- +title: Руководство по быстрому старту +content_template: templates/task +weight: 40 +--- + +{{% capture overview %}} + +На этой странице показано, как использовать скрипт `update-imported-docs` для генерации справочной документации Kubernetes. Скрипт автоматизирует настройку сборки и генерирует справочную документацию для выпуска. + +{{% /capture %}} + +{{% capture prerequisites %}} + +{{< include "prerequisites-ref-docs.md" >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Получение репозитория документации + +Убедитесь, что ваша копия репозитория `website` обновлена в соответствии с оригинальным репозиторием `kubernetes/website`, а затем склонируйте вашу копию `website`. + +```shell +mkdir github.com +cd github.com +git clone git@github.com:/website.git +``` + +Определите базовую директорию вашей копии. Например, при выполнении предыдущего блока команд, то базовой директорией будет `website`. Далее в этом руководстве базовая директория в командах будет обозначаться ``. + +{{< note>}} +Если вы хотите изменить контент инструментов компонента и справочник API, посмотрите [руководство по участию в оригинальной документации](/docs/contribute/generate-ref-docs/contribute-upstream). +{{< /note >}} + +## Краткий обзор update-imported-docs + +Скрипт `update-imported-docs` находится в директории `/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`. +1. Запускает команды в клонированных репозиториях для подготовки генератора документации, а затем генерирует файлы HTML и Markdown. +1. Копирует сгенерированные файлы HTML и Markdown в локальную копию репозитория `` в директории, указанные в конфигурационном файле. +1. Обновляет ссылки на команды `kubectl` из `kubectl`.md, ссылаясь на разделы в справочнике по команде `kubectl`. +. +Когда сгенерированные файлы находятся в вашем локальной копии репозитория ``, вы можете отправить их в виде [пулреквеста](/ru/docs/contribute/start/) в оригинальный репозиторий ``. + +## Формат конфигурационного файла + +Каждый конфигурационный файл может содержать несколько репозиториев, которые будут импортированы вместе. При необходимости вы можете вручную изменить конфигурационный файл. Вы можете создавать новые конфигурационные файлы для импорта других групп документации. +Ниже приведен пример файла конфигурации в формате YAML: + +```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-файл документации, импортированный инструментом, должен соответствовать [руководству по оформлению документации](/docs/contribute/style/style-guide/). + +## Настройка reference.yml + +Откройте файл `/update-imported-docs/reference.yml` для редактирования. +Не изменяйте значение в поле `generate-command`, если не понимаете, как эта команда используется для сборки справочников. +Вам нет необходимости править файл `reference.yml`. В некоторых случаях изменения в исходном коде основного репозитория могут потребовать внесения изменений в конфигурационный файл (например, зависимости версий golang и изменения сторонних библиотек). +Если у вас возникли проблемы со сборкой, обратитесь за помощью к команде SIG-Docs на канале [#sig-docs в Slack Kubernetes](https://kubernetes.slack.com). + +{{< note >}} +Команда `generate-command` является необязательной, её можно использовать для выполнения указанной команды или небольшого скрипта, чтобы сгенерировать документацию из репозитория. +{{< /note >}} + +В файле `reference.yml` секция `files` содержат список полей `src` и `dst`. +В поле `src` хранится путь к сгенерированному Markdown-файлу в клонированной директории сборки `kubernetes-sigs/reference-docs`, а поле `dst` определяет, куда скопировать этот файл в клонированном репозитории `kubernetes/website`. +Например: + +```yaml +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`. +Например: + +```yaml + files: + - src: gen-compdocs/build/kubeadm*.md + dst: content/en/docs/reference/setup-tools/kubeadm/generated/ +``` + +## Запуск инструмента update-imported-docs + +Вы можете запустить инструмент `update-imported-docs` следующим образом: + +```shell +cd /update-imported-docs +./update-imported-docs +``` + +Например: + +```shell +./update-imported-docs reference.yml 1.17 +``` + + +## Исправление ссылок + +Конфигурационный файл `release.yml` содержит инструкции по исправлению относительных ссылок +Для исправления относительных ссылок в импортированных файлах, установите для свойство `gen-absolute-links` в значение `true`. В качестве примера можете посмотреть файл [`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml). + +## Внесение изменений в kubernetes/website + +Список сгенерированных и скопированных файлов в `` можно узнать, как показано ниже: + +```shell +cd +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`. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят. + +Спустя несколько минут после принятия вашего пулреквеста, обновленные темы справочника будут отображены в [документации](/ru/docs/home/). + +{{% /capture %}} + +{{% capture whatsnext %}} + +Для генерации отдельной взятой справочной документации путём ручной настройки необходимых репозиториев сборки и выполнении скриптов сборки обратитесь к следующим руководствам: + +* [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/) +* [Генерация справочной документации для команд kubectl](/ru/docs/contribute/generate-ref-docs/kubectl/) +* [Генерация справочной документации для API Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-api/) + +{{% /capture %}} diff --git a/content/ru/docs/templates/feature-state-alpha.txt b/content/ru/docs/templates/feature-state-alpha.txt new file mode 100644 index 0000000000..ae3c2e8532 --- /dev/null +++ b/content/ru/docs/templates/feature-state-alpha.txt @@ -0,0 +1,7 @@ +В настоящее время данная функциональность находится в состоянии *alpha*, это означает, что: + +* Названия версий включают надпись "alpha" (например, v1alpha1). +* Могут быть баги. Работа с этой функциональностью может привести к ошибкам. Поэтому по умолчанию она отключена. +* Поддержка функциональности может быть прекращена в любое время без предупреждения. +* API может быть несовместим с более поздними версиями без предупреждения. +* Рекомендуется для использования только в тестировочных кластерах с коротким жизненным циклом из-за высокого риска наличия багов и отсутствия долгосрочной поддержки. \ No newline at end of file diff --git a/content/ru/docs/templates/feature-state-beta.txt b/content/ru/docs/templates/feature-state-beta.txt new file mode 100644 index 0000000000..7e4f0d91b6 --- /dev/null +++ b/content/ru/docs/templates/feature-state-beta.txt @@ -0,0 +1,8 @@ +В настоящее время данная функциональность находится в состоянии *beta*, это означает, что: + +* Названия версий включают надпись "beta" (например, v2beta3). +* Код хорошо протестирован. Активация этой функциональности — безопасно. Поэтому она включена по умолчанию. +* Поддержка функциональности в целом не будет прекращена, хотя детали могут измениться. +* Схема и/или семантика объектов может стать несовместимой с более поздними бета-версиями или стабильными выпусками. Когда это случится, мы даим инструкции по миграции на следующую версию. Это обновление может включать удаление, редактирование и повторного создание API-объектов. Этот процесс может потребовать тщательного анализа. Кроме этого, он может привести к простою приложений, которые используют данную функциональность. +* Рекомендуется только для неосновного производственного использования из-за риска возникновения возможных несовместимых изменений с будущими версиями. Если у вас есть несколько кластеров, которые возможно обновить независимо, вы можете снять это ограничение. +* **Пожалуйста, попробуйте в действии бета-версии функциональности и поделитесь своими впечатлениями! После того, как функциональность выйдет из бета-версии, нам может быть нецелесообразно что-то дальше изменять.** diff --git a/content/ru/docs/templates/feature-state-deprecated.txt b/content/ru/docs/templates/feature-state-deprecated.txt new file mode 100644 index 0000000000..c3ef2b815c --- /dev/null +++ b/content/ru/docs/templates/feature-state-deprecated.txt @@ -0,0 +1,2 @@ + +Данная функциональность объявлена *устаревшей*. Для получения дополнительной информации об этом состоянии перейдите на страницу [Политика управления устаревшими версиями Kubernetes](/docs/reference/deprecation-policy/). \ No newline at end of file diff --git a/content/ru/docs/templates/feature-state-stable.txt b/content/ru/docs/templates/feature-state-stable.txt new file mode 100644 index 0000000000..4e13386e62 --- /dev/null +++ b/content/ru/docs/templates/feature-state-stable.txt @@ -0,0 +1,5 @@ + +Данная функциональность является *стабильной*, это означает, что: + +* Версии именуются по шаблону vX, где X — это целое число. +* Стабильные версии функциональности будут доступны во многих последующих выпусках. \ No newline at end of file diff --git a/content/ru/docs/templates/index.md b/content/ru/docs/templates/index.md new file mode 100644 index 0000000000..9d7bccd143 --- /dev/null +++ b/content/ru/docs/templates/index.md @@ -0,0 +1,13 @@ +--- +headless: true + +resources: +- src: "*alpha*" + title: "alpha" +- src: "*beta*" + title: "beta" +- src: "*deprecated*" + title: "deprecated" +- src: "*stable*" + title: "stable" +--- diff --git a/content/ru/includes/prerequisites-ref-docs.md b/content/ru/includes/prerequisites-ref-docs.md new file mode 100644 index 0000000000..bc43abc19c --- /dev/null +++ b/content/ru/includes/prerequisites-ref-docs.md @@ -0,0 +1,20 @@ + +### Требования: + +- Наличие компьютера под управлением ОС Linux или macOS. + +- Установленные следующие инструменты: + + - [Python](https://www.python.org/downloads/) версии 3.7.x + - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - [Golang](https://golang.org/doc/install) версии 1.13+ + - [Pip](https://pypi.org/project/pip/), который потребуется для установки PyYAML + - [PyYAML](https://pyyaml.org/) версии 5.1.2 + - [make](https://www.gnu.org/software/make/) + - [gcc compiler/linker](https://gcc.gnu.org/) + - [Docker](https://docs.docker.com/engine/installation/) (требуется только для справочника команды `kubectl`) + +- В переменной окружении `PATH` должны прописаны пути до необходимых инструментов сборки, таких как `Go` и `python`. + +- Вам нужно знать, как создать пулреквест в репозитории на GitHub. + Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел [Работа из локальной копии](/ru/docs/contribute/intermediate/#работа-из-локальной-копии). diff --git a/i18n/ru.toml b/i18n/ru.toml index 8e8b1c6275..19b8e21a1a 100644 --- a/i18n/ru.toml +++ b/i18n/ru.toml @@ -13,7 +13,7 @@ other = "Цели" other = "Очистка" [prerequisites_heading] -other = "Прежде чем вы начнете" +other = "Подготовка к работе" [whatsnext_heading] other = "Что дальше"