8000 Translate Reference Docs Overview section into Russian (#19284) · kubernetes/website@0181d88 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0181d88

Browse files
lex111lex111
authored
Translate Reference Docs Overview section into Russian (#19284)
1 parent 646b7a5 commit 0181d88

File tree

13 files changed

+916
-1
lines changed

13 files changed

+916
-1
lines changed

‎content/ru/docs/contribute/generate-ref-docs/_index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Обзор справочной документации
3+
main_menu: true
4+
weight: 80
5+
---
6+
7+
Темы в этом разделе описывают, как генерировать справочные руководства Kubernetes.
8+
9+
Для сборки справочной документации посмотрите следующий ресурс:
10+
11+
* [Краткое руководство по генерации справочной документации](/docs/contribute/generate-ref-docs/quickstart/)

‎content/ru/docs/contribute/generate-ref-docs/contribute-upstream.md‎

Lines changed: 185 additions & 0 deletions
Large diffs are not rendered by default.

‎content/ru/docs/contribute/generate-ref-docs/kubectl.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: Генерация справочной документации для команд kubectl
3+
content_template: templates/task
4+
weight: 90
5+
---
6+
7+
{{% capture overview %}}
8+
9+
На этой странице показано, как сгенерировать справочник для команды `kubectl`.
10+
11+
{{< note >}}
12+
На этой странице показывается, как сгенерировать справочную документацию для таких [команд 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).
13+
Этот раздел не рассматривает генерацию справочной страницы для опций [kubectl](/ru/docs/reference/generated/kubectl/kubectl/). Инструкции по генерации справочной страницы опций kubectl смотрите в разделе [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/).
14+
{{< /note >}}
15+
16+
{{% /capture %}}
17+
18+
{{% capture prerequisites %}}
19+
20+
{{< include "prerequisites-ref-docs.md" >}}
21+
22+
{{% /capture %}}
23+
24+
{{% capture steps %}}
25+
26+
## Настройка локальных репозиториев
27+
28+
Создайте рабочую область и определите переменную окружения `GOPATH`.
29+
30+
```shell
31+
mkdir -p $HOME/<workspace>
32+
33+
export GOPATH=$HOME/<workspace>
34+
```
35+
36+
Загрузите локальные копии следующих репозиториев:
37+
38+
```shell
39+
go get -u github.com/spf13/pflag
40+
go get -u github.com/spf13/cobra
41+
go get -u gopkg.in/yaml.v2
42+
go get -u kubernetes-sigs/reference-docs
43+
```
44+
45+
Если у вас ещё нет копии репозитория kubernetes/website, клонируйте её на свой компьютер:
46+
47+
```shell
48+
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
49+
```
50+
51+
Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes:
52+
53+
```shell
54+
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
55+
```
56+
57+
Удалите пакет spf13 в `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
58+
59+
```shell
60+
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
61+
```
62+
63+
В репозитории kubernetes/kubernetes использует исходный код `kubectl` и `kustomize`.
64+
65+
* Определите базовую директорию вашей копии репозитория [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
66+
Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/k8s.io/kubernetes`.
67+
В остальных командах базовая директория будет именоваться как `<k8s-base>`.
68+
69+
* Определите базовую директорию вашей копии репозитория [kubernetes/website](https://github.com/kubernetes/website).
70+
Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com/<your-username>/website`.
71+
В остальных команд базовая директория будет именоваться как `<web-base>`.
72+
73+
* Определите базовую директорию вашей копии репозитория [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs).
74+
Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`.
75+
В остальных команд базовая директория будет именоваться как `<rdocs-base>`.
76+
77+
В вашем локальном репозитории k8s.io/kubernetes переключитесь в нужную вам ветку и убедитесь, что она в актуальном состоянии. Например, если вам нужно сгенерировать документацию для Kubernetes 1.17, вы можете использовать эти команды:
78+
79+
```shell
80+
cd <k8s-base>
81+
git checkout v1.17.0
82+
git pull https://github.com/kubernetes/kubernetes v1.17.0
83+
```
84+
85+
Если вам не нужно изменять исходный код `kubectl`, следуйте инструкциям по [определению переменных сборки](#настройка-переменных-для-сборки).
86+
87+
## Редактирование исходного кода kubectl
88+
89+
Справочная документация по команде kubectl генерируется автоматически из исходного кода kubectl. Если вы хотите изменить справочную документацию, сначала измените один или несколько комментариев в исходном коде kubectl. Сделайте изменения в локальный репозиторий kubernetes/kubernetes, а затем отправьте пулреквест в ветку master репозитория [github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
90+
91+
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) — пример пулреквеста, который исправляет опечатку в исходном коде kubectl.
92+
93+
Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят в ветку master репозитория kubernetes/kubernetes.
94+
95+
## Применение вашего изменения в ветку выпуска
96+
97+
Теперь ваше изменение в ветке master, которая используется для разработки следующего выпуска Kubernetes. Если вы хотите добавить ваше изменение в документацию для уже выпущенной версии Kubernetes, вам нужно применить коммит с соответствующим изменением в нужную ветку выпуска.
98+
99+
Например, предположим, что ветка master используется для разработки Kubernetes 1.10, а вам нужно бэкпортировать ваше изменение в ветку release-1.15. За инструкциями обратитесь к странице [Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
100+
101+
Отслеживайте ваш пулреквест с применённым изменением до тех пор, пока он не будет объединён в ветку выпуска.
102+
103+
{{< note >}}
104+
Применение коммита требует наличия возможности добавить метку и этап в вашем пулреквесте. Если у вас нет таких разрешений, вам нужно переговорить с кем-то, кто может сделать это для вас.
105+
{{< /note >}}
106+
107+
## Настройка переменных для сборки
108+
109+
Перейдите на `<rdocs-base>`. В командной строке установите следующие переменные окружения.
110+
111+
* `K8S_ROOT` со значением `<k8s-base>`.
112+
* `WEB_ROOT` со значением `<web-base>`.
113+
* `K8S_RELEASE` со значением нужной версии документации.
114+
Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения `K8S_RELEASE` со значением 1.17.
115+
116+
Примеры:
117+
118+
```shell
119+
export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
120+
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
121+
export K8S_RELEASE=1.17
122+
```
123+
124+
## Создание версионированной директории
125+
126+
Скрипт сборки `createversiondirs` создаёт версионированную директорию и копирует туда конфигурационные файлы справочника kubectl.
127+
Имя версионированной директории имеет следующий вид: `v<major>_<minor>`.
128+
129+
В директории `<rdocs-base>` выполнение следующий скрипт сборки:
130+
131+
```shell
132+
cd <rdocs-base>
133+
make createversiondirs
134+
```
135+
136+
## Переход в тег выпуска в k8s.io/kubernetes
137+
138+
В вашем локальном репозитории `<k8s-base>` перейдите в ветку с версией Kubernetes, для которой вы хотите получить документацию. Например, если вы хотите сгенерировать документацию для Kubernetes 1.17, перейдите в тег `v1.17.0`. Убедитесь, что ваша локальная ветка содержит актуальные изменения.
139+
140+
```shell
141+
cd <k8s-base>
142+
git checkout v1.17.0
143+
git pull https://github.com/kubernetes/kubernetes v1.17.0
144+
```
145+
146+
## Выполнение кода для генерации документации
147+
148+
В вашей локальной директории `<rdocs-base>` запустите скрипт сборки `copycli`. Команда выполняется от пользователя `root`:
149+
150+
```shell
151+
cd <rdocs-base>
152+
make copycli
153+
```
154+
155+
Команда `copycli` удаляет временную директорию сборки, генерирует файлы команды kubectl и копирует полученную HTML-страницу справочника команде kubectl и ресурсы в `<web-base>`.
156+
157+
## Проверка сгенерированных файлов
158+
159+
Убедитесь в том, что перечисленные ниже два файлы были сгенерированы:
160+
161+
```shell
162+
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
163+
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
164+
```
165+
166+
## Проверка скопированных файлов
167+
168+
Убедитесь в том, все сгенерированные файлы были скопированы в вашу директорию `<web-base>`:
169+
170+
```shell
171+
cd <web-base>
172+
git status
173+
```
174+
175+
В выводе должны перечислены изменённые файлы:
176+
177+
```
178+
static/docs/reference/generated/kubectl/kubectl-commands.html
179+
static/docs/reference/generated/kubectl/navData.js
180+
```
181+
182+
Также в выводе должно быть:
183+
184+
```
185+
static/docs/reference/generated/kubectl/scroll.js
186+
static/docs/reference/generated/kubectl/stylesheet.css
187+
static/docs/reference/generated/kubectl/tabvisibility.js
188+
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
189+
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
190+
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
191+
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
192+
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css
193+
```
194+
195+
## Проверка документации локально
196+
197+
Соберите документацию Kubernetes в вашей директории `<web-base>`.
198+
199+
```shell
200+
cd <web-base>
201+
make docker-serve
202+
```
203+
204+
Посмотрите [локальную предварительную версию сайта](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/).
205+
206+
## Добавление и фиксация изменений в kubernetes/website
207+
208+
Выполните команду `git add` и `git commit` для фиксации файлов.
209+
210+
## Создание пулреквеста
211+
212+
Создайте пулреквест в репозиторий `kubernetes/website`. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.
213+
214+
Спустя несколько минут после принятия вашего пулреквеста, обновленные темы справочника будут отображены в [документации](/ru/docs/home/).
215+
216+
{{% /capture %}}
217+
218+
{{% capture whatsnext %}}
219+
220+
* [Руководство по быстрому старту генерации справочной документации](/ru/docs/contribute/generate-ref-docs/quickstart/)
221+
* [Генерация справочной документации для компонентов и инструментов Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-components/)
222+
* [Генерация справочной документации для API Kubernetes](/ru/docs/contribute/generate-ref-docs/kubernetes-api/)
223+
224+
{{% /capture %}}

0 commit comments

Comments
 (0)
0