Skip to content

Commit 280496c

Browse files
jihoon-seojihoon-seo
committed
[ko] Translate generate-ref-docs (partial)
1 parent 5d949f9 commit 280496c

File tree

3 files changed

+283
-4
lines changed

3 files changed

+283
-4
lines changed

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
title: 참조 문서 개요
2+
title: 레퍼런스 문서 개요
33
main_menu: true
44
weight: 80
55
---
66

7-
이 섹션은 쿠버네티스 참조 가이드를 생성하는 방법에 대해 설명한다.
7+
이 섹션은 쿠버네티스 레퍼런스 가이드를 생성하는 방법에 대해 설명한다.
88

9-
참조 문서화 시스템을 빌드하려면, 다음의 가이드를 참고한다.
9+
레퍼런스 문서를 생성하려면, 다음의 가이드를 참고한다.
1010

11-
* [참조 문서 생성에 대한 퀵스타트 가이드](/docs/contribute/generate-ref-docs/quickstart/)
11+
* [레퍼런스 문서 생성에 대한 퀵스타트 가이드](/ko/docs/contribute/generate-ref-docs/quickstart/)

‎content/ko/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
2+
### 필요 사항: {#Requirements}
3+
4+
- 리눅스 또는 macOS 로 구동되는 개발 환경이 필요하다.
5+
6+
- 다음의 도구들이 설치되어 있어야 한다.
7+
8+
- [Python](https://www.python.org/downloads/) v3.7.x
9+
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
10+
- [Golang](https://golang.org/doc/install) version 1.13+
11+
- [Pip](https://pypi.org/project/pip/) (PyYAML 설치에 필요함)
12+
- [PyYAML](https://pyyaml.org/) v5.1.2
13+
- [make](https://www.gnu.org/software/make/)
14+
- [gcc compiler/linker](https://gcc.gnu.org/)
15+
- [Docker](https://docs.docker.com/engine/installation/) (`kubectl` 명령어 레퍼런스 업데이트에만 필요함)
16+
17+
- 위에 나열된 도구들 (예: `Go` 바이너리나 `python`) 을 사용할 수 있도록 `PATH` 환경 변수를 알맞게 설정해야 한다.
18+
19+
- GitHub 저장소로 풀 리퀘스트를 생성하는 방법을 알고 있어야 한다.
20+
이를 위해 `kubernetes/website` 저장소를 개인 계정으로 포크해야 한다.
21+
더 자세한 내용은 [로컬 포크에서 작업하기](/ko/docs/contribute/new-content/open-a-pr/#fork-the-repo)를 참조한다.
22+

‎content/ko/docs/contribute/generate-ref-docs/quickstart.md

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
title: 퀵스타트 가이드
3+
content_type: task
4+
weight: 40
5+
---
6+
7+
<!-- overview -->
8+
9+
이 문서에서는 `update-imported-docs` 스크립트를 사용하여
10+
쿠버네티스 레퍼런스 문서를 생성하는 방법에 대해 설명한다.
11+
이 스크립트는 특정 쿠버네티스 릴리스 버전에 대해 빌드 설정을 자동으로 수행하고 레퍼런스 문서를 생성한다.
12+
13+
## {{% heading "prerequisites" %}}
14+
15+
{{< include "prerequisites-ref-docs.md" >}}
16+
17+
<!-- steps -->
18+
19+
## `website` 저장소 클론하기 {#Getting-the-docs-repository}
20+
21+
개인 계정에 있는 포크 버전의 `website` 저장소가 `kubernetes/website` 저장소의 master 브랜치만큼 최신인지 확인한 뒤,
22+
개인 계정에 있는 포크 버전의 `website` 저장소를 로컬 개발 환경으로 클론한다.
23+
24+
```shell
25+
mkdir github.com
26+
cd github.com
27+
git clone [email protected]:<your_github_username>/website.git
28+
```
29+
30+
아래에서 사용될 '베이스 디렉터리'를 숙지해야 한다. 예를 들어 위에 안내된 대로
31+
저장소를 클론했다면, 베이스 디렉터리는
32+
`github.com/website` 가 된다. 이제 이 문서의 나머지 부분에서 `<web-base>` 라는 구문이 나오면
33+
이 부분에 당신의 베이스 디렉터리를 대입하면 된다.
34+
35+
{{< note>}}
36+
만약 쿠버네티스 구성 도구와 API 레퍼런스에 기여하고 싶다면,
37+
[업스트림 코드에 기여하기 (영문)](/docs/contribute/generate-ref-docs/contribute-upstream) 를 참조한다.
38+
{{< /note >}}
39+
40+
## `update-imported-docs` 스크립트 개요 {#Overview-of-update-imported-docs}
41+
42+
`update-imported-docs` 스크립트는 `<web-base>/update-imported-docs/`
43+
디렉터리에 존재한다.
44+
45+
이 스크립트는 다음 레퍼런스를 생성한다.
46+
47+
* 구성요소 및 도구 레퍼런스 페이지
48+
* `kubectl` 명령어 레퍼런스
49+
* 쿠버네티스 API 레퍼런스
50+
51+
`update-imported-docs` 스크립트는 쿠버네티스 소스코드로부터 레퍼런스 문서를
52+
생성한다. 스크립트가 실행되면 개발 머신의 `/tmp` 디렉터리 아래에 임시 디렉터리를
53+
생성하고, 이 임시 디렉터리 아래에 레퍼런스 문서 생성에 필요한 `kubernetes/kubernetes` 저장소와
54+
`kubernetes-sigs/reference-docs` 저장소를 클론하며,
55+
`GOPATH` 환경 변수를 이 임시 디렉터리로 지정한다.
56+
또한 이 스크립트는 다음의 환경 변수를 설정한다.
57+
58+
* `K8S_RELEASE`
59+
* `K8S_ROOT`
60+
* `K8S_WEBROOT`
61+
62+
스크립트가 정상적으로 실행되려면 인자 2개를 전달해야 한다.
63+
64+
* 환경설정 YAML 파일 (`reference.yml`)
65+
* 쿠버네티스 릴리스 버전 (예: `1.17`)
66+
67+
환경설정 파일은 `generate-command` 라는 필드를 포함하는데,
68+
이 필드에는
69+
`kubernetes-sigs/reference-docs/Makefile` 에 있는 Make 타겟들을 활용하여 빌드하는 일련의 과정이 명시되어 있다.
70+
`K8S_RELEASE` 환경 변수는 릴리스 버전을 결정한다.
71+
72+
`update-imported-docs` 스크립트는 다음의 과정을 수행한다.
73+
74+
1. 환경설정 파일에 있는 관련 저장소를 클론한다.
75+
레퍼런스 문서 생성을 위해
76+
기본적으로는 `kubernetes-sigs/reference-docs` 저장소를 클론하도록 되어 있다.
77+
1. 클론한 안에서, 문서 생성에 필요한 사항을 준비하기 위한 명령어를 실행한 뒤,
78+
HTML 파일과 마크다운 파일을 생성한다.
79+
1. 생성된 HTML 파일과 마크다운 파일을
80+
환경설정 파일에 명시된 규칙에 따라 `<web-base>` 로 복사한다.
81+
1. `kubectl`.md 에 있는 `kubectl` 명령어 링크들이
82+
`kubectl` 명령어 레퍼런스 페이지의 올바른 섹션으로 연결되도록 업데이트한다.
83+
84+
생성된 파일이 `<web-base>` 아래에 복사되었으면,
85+
`kubernetes/website` 저장소로 [풀 리퀘스트를 생성](/ko/docs/contribute/new-content/open-a-pr/)
86+
할 수 있다.
87+
88+
## 환경설정 파일 형식 {#Configuration-file-format}
89+
90+
각 환경설정 파일은 레퍼런스 생성을 위해 필요한 여러 저장소의 정보를 담을 수 있다.
91+
필요한 경우, 환경설정 파일을 직접 수정하여 사용할 수도 있다.
92+
또는, 다른 그룹의 문서를 임포트하기 위해 새로운 환경설정 파일을 작성할 수도 있다.
93+
다음은 환경설정 YAML 파일의 예시이다.
94+
95+
```yaml
96+
repos:
97+
- name: community
98+
remote: https://github.com/kubernetes/community.git
99+
branch: master
100+
files:
101+
- src: contributors/devel/README.md
102+
dst: docs/imported/community/devel.md
103+
- src: contributors/guide/README.md
104+
dst: docs/imported/community/guide.md
105+
```
106+
107+
이 도구에 의해 처리될 단일 페이지 마크다운 문서는
108+
[문서 스타일 가이드](/docs/contribute/style/style-guide/)의 내용을 만족해야 한다.
109+
110+
## reference.yml 환경설정 파일 다루기 {#Customizing-reference-yml}
111+
112+
`<web-base>/update-imported-docs/reference.yml` 환경설정 파일을 열어 수정할 수 있다.
113+
레퍼런스 문서 생성을 위해 명령어들이 어떻게 사용되고 있는지 파악하지 못했다면,
114+
`generate-command` 필드의 내용은 수정하지 말아야 한다.
115+
대부분의 경우 `reference.yml` 을 직접 수정해야 할 필요는 없다.
116+
때때로, 업스트림 소스코드 업데이트 때문에 이 환경설정 파일을 수정해야 할 수도 있다.
117+
(예: Golang 버전 의존성, 서드파티 라이브러리 변경 등)
118+
만약 스크립트 사용 시 빌드 문제가 있다면,
119+
[쿠버네티스 슬랙의 #sig-docs 채널](https://kubernetes.slack.com/archives/C1J0BPD2M)에서 SIG-Docs 팀에 문의하면 된다.
120+
121+
{{< note >}}
122+
`generate-command` 는 특정 저장소로부터 문서를 만들기 위한
123+
명령어나 스크립트를 실행하기 위해 사용할 수 있는 선택적 필드이다.
124+
{{< /note >}}
125+
126+
`reference.yml` 환경설정 파일에서, `files` 필드는 `src` 와 `dst` 필드를 포함한다.
127+
`src` 필드에는 `kubernetes-sigs/reference-docs` 디렉터리 아래에 있는 생성된 마크다운 파일의 위치를 명시하고,
128+
`dst` 필드에는 이 파일을
129+
`kubernetes/website` 디렉터리 아래의 어느 위치로 복사할지를 명시한다.
130+
예시는 다음과 같다.
131+
132+
```yaml
133+
repos:
134+
- name: reference-docs
135+
remote: https://github.com/kubernetes-sigs/reference-docs.git
136+
files:
137+
- src: gen-compdocs/build/kube-apiserver.md
138+
dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
139+
...
140+
```
141+
142+
만약 하나의 `src` 디렉터리에서 하나의 `dst` 디렉터리로 많은 파일이 복사되어야 한다면,
143+
`src` 필드에 와일드카드를 사용할 수 있다.
144+
이 경우, `dst` 필드에는 단일 파일의 경로가 아니라 디렉터리의 경로를 명시해야 한다.
145+
예시는 다음과 같다.
146+
147+
```yaml
148+
files:
149+
- src: gen-compdocs/build/kubeadm*.md
150+
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
151+
```
152+
153+
## `update-imported-docs` 도구 실행하기 {#Running-the-update-imported-docs-tool}
154+
155+
다음과 같이 `update-imported-docs` 도구를 실행할 수 있다.
156+
157+
```shell
158+
cd <web-base>/update-imported-docs
159+
./update-imported-docs <configuration-file.yml> <release-version>
160+
```
161+
162+
예를 들면 다음과 같다.
163+
164+
```shell
165+
./update-imported-docs reference.yml 1.17
166+
```
167+
168+
<!-- Revisit: is the release configuration used -->
169+
## 링크 업데이트하기 {#Fixing-Links}
170+
171+
`release.yml` 환경설정 파일은 상대경로 링크를 수정하는 방법을 포함하고 있다.
172+
임포트하는 파일 안에 있는 상대경로 링크를 수정하려면, `gen-absolute-links` 필드를
173+
`true` 로 명시한다. 이에 대한 예시는
174+
[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml) 에서 볼 수 있다.
175+
176+
## `kubernetes/website` 의 변경사항을 커밋하기 {#Adding-and-committing-changes-in-kubernetes-website}
177+
178+
다음의 명령을 실행하여, 스크립트에 의해 생성된 뒤 `<web-base>` 아래에 복사된 파일의 목록을 볼 수 있다.
179+
180+
```shell
181+
cd <web-base>
182+
git status
183+
```
184+
185+
위의 명령을 실행하면 새로 추가된 파일과 수정된 파일의 목록을 볼 수 있다.
186+
아래의 결과 예시는 업스트림 소스코드의 변경사항에 따라 다르게 나타날 수 있다.
187+
188+
### 생성된 구성요소 도구 레퍼런스 {#Generated-component-tool-files}
189+
190+
```
191+
content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
192+
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
193+
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
194+
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
195+
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
196+
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
197+
content/en/docs/reference/kubectl/kubectl.md
198+
```
199+
200+
### 생성된 kubectl 명령어 레퍼런스 {#Generated-kubectl-command-reference-files}
201+
202+
```
203+
static/docs/reference/generated/kubectl/kubectl-commands.html
204+
static/docs/reference/generated/kubectl/navData.js
205+
static/docs/reference/generated/kubectl/scroll.js
206+
static/docs/reference/generated/kubectl/stylesheet.css
207+
static/docs/reference/generated/kubectl/tabvisibility.js
208+
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
209+
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
210+
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
211+
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
212+
static/docs/reference/generated/kubectl/css/font-awesome.min.css
213+
```
214+
215+
### 생성된 쿠버네티스 API 레퍼런스 와 파일 {#Generated-Kubernetes-API-reference-directories-and-files}
216+
217+
```
218+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html
219+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js
220+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js
221+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/query.scrollTo.min.js
222+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css
223+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css
224+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css
225+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf
226+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot
227+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg
228+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf
229+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff
230+
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2
231+
```
232+
233+
`git add` 와 `git commit` 명령을 실행하여 추가/변경된 파일을 커밋한다.
234+
235+
## 풀 리퀘스트 만들기 {#Creating-a-pull-request}
236+
237+
`kubernetes/website` 저장소에 풀 리퀘스트를 등록한다.
238+
등록한 풀 리퀘스트를 모니터하고, 리뷰 커멘트가 달리면 그에 대해 대응을 한다.
239+
풀 리퀘스트가 머지될 때 까지 계속 모니터한다.
240+
241+
풀 리퀘스트가 머지된 뒤 몇 분이 지나면,
242+
변경사항을
243+
[쿠버네티스 문서 홈페이지](/docs/home/)에서 확인할 수 있다.
244+
245+
246+
247+
## {{% heading "whatsnext" %}}
248+
249+
250+
수동으로 빌드 저장소를 설정하고 빌드 타겟을 실행하여 개별 레퍼런스 문서를 생성하려면,
251+
다음의 가이드를 참고한다.
252+
253+
* [쿠버네티스 구성요소와 도구에 대한 레퍼런스 문서 생성하기](/docs/contribute/generate-ref-docs/kubernetes-components/)
254+
* [kubectl 명령어에 대한 레퍼런스 문서 생성하기](/docs/contribute/generate-ref-docs/kubectl/)
255+
* [쿠버네티스 API에 대한 레퍼런스 문서 생성하기](/docs/contribute/generate-ref-docs/kubernetes-api/)
256+
257+

0 commit comments

Comments
 (0)