From 280496cd6dbf0d4d17b6165ae1654c449beb8a7d Mon Sep 17 00:00:00 2001 From: Jihoon Seo Date: Thu, 25 Mar 2021 09:47:58 +0900 Subject: [PATCH] [ko] Translate generate-ref-docs (partial) --- .../contribute/generate-ref-docs/_index.md | 8 +- .../prerequisites-ref-docs.md | 22 ++ .../generate-ref-docs/quickstart.md | 257 ++++++++++++++++++ 3 files changed, 283 insertions(+), 4 deletions(-) create mode 100644 content/ko/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md create mode 100644 content/ko/docs/contribute/generate-ref-docs/quickstart.md diff --git a/content/ko/docs/contribute/generate-ref-docs/_index.md b/content/ko/docs/contribute/generate-ref-docs/_index.md index 756c509206..ad9d221f15 100644 --- a/content/ko/docs/contribute/generate-ref-docs/_index.md +++ b/content/ko/docs/contribute/generate-ref-docs/_index.md @@ -1,11 +1,11 @@ --- -title: 참조 문서 개요 +title: 레퍼런스 문서 개요 main_menu: true weight: 80 --- -이 섹션은 쿠버네티스 참조 가이드를 생성하는 방법에 대해 설명한다. +이 섹션은 쿠버네티스 레퍼런스 가이드를 생성하는 방법에 대해 설명한다. -참조 문서화 시스템을 빌드하려면, 다음의 가이드를 참고한다. +레퍼런스 문서를 생성하려면, 다음의 가이드를 참고한다. -* [참조 문서 생성에 대한 퀵스타트 가이드](/docs/contribute/generate-ref-docs/quickstart/) \ No newline at end of file +* [레퍼런스 문서 생성에 대한 퀵스타트 가이드](/ko/docs/contribute/generate-ref-docs/quickstart/) diff --git a/content/ko/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md b/content/ko/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md new file mode 100644 index 0000000000..b7c77889d8 --- /dev/null +++ b/content/ko/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md @@ -0,0 +1,22 @@ + +### 필요 사항: {#Requirements} + +- 리눅스 또는 macOS 로 구동되는 개발 환경이 필요하다. + +- 다음의 도구들이 설치되어 있어야 한다. + + - [Python](https://www.python.org/downloads/) v3.7.x + - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - [Golang](https://golang.org/doc/install) version 1.13+ + - [Pip](https://pypi.org/project/pip/) (PyYAML 설치에 필요함) + - [PyYAML](https://pyyaml.org/) v5.1.2 + - [make](https://www.gnu.org/software/make/) + - [gcc compiler/linker](https://gcc.gnu.org/) + - [Docker](https://docs.docker.com/engine/installation/) (`kubectl` 명령어 레퍼런스 업데이트에만 필요함) + +- 위에 나열된 도구들 (예: `Go` 바이너리나 `python`) 을 사용할 수 있도록 `PATH` 환경 변수를 알맞게 설정해야 한다. + +- GitHub 저장소로 풀 리퀘스트를 생성하는 방법을 알고 있어야 한다. +이를 위해 `kubernetes/website` 저장소를 개인 계정으로 포크해야 한다. +더 자세한 내용은 [로컬 포크에서 작업하기](/ko/docs/contribute/new-content/open-a-pr/#fork-the-repo)를 참조한다. + diff --git a/content/ko/docs/contribute/generate-ref-docs/quickstart.md b/content/ko/docs/contribute/generate-ref-docs/quickstart.md new file mode 100644 index 0000000000..6e3fbb5263 --- /dev/null +++ b/content/ko/docs/contribute/generate-ref-docs/quickstart.md @@ -0,0 +1,257 @@ +--- +title: 퀵스타트 가이드 +content_type: task +weight: 40 +--- + + + +이 문서에서는 `update-imported-docs` 스크립트를 사용하여 +쿠버네티스 레퍼런스 문서를 생성하는 방법에 대해 설명한다. +이 스크립트는 특정 쿠버네티스 릴리스 버전에 대해 빌드 설정을 자동으로 수행하고 레퍼런스 문서를 생성한다. + +## {{% heading "prerequisites" %}} + +{{< include "prerequisites-ref-docs.md" >}} + + + +## `website` 저장소 클론하기 {#Getting-the-docs-repository} + +개인 계정에 있는 포크 버전의 `website` 저장소가 `kubernetes/website` 저장소의 master 브랜치만큼 최신인지 확인한 뒤, +개인 계정에 있는 포크 버전의 `website` 저장소를 로컬 개발 환경으로 클론한다. + +```shell +mkdir github.com +cd github.com +git clone git@github.com:/website.git +``` + +아래에서 사용될 '베이스 디렉터리'를 숙지해야 한다. 예를 들어 위에 안내된 대로 +저장소를 클론했다면, 베이스 디렉터리는 +`github.com/website` 가 된다. 이제 이 문서의 나머지 부분에서 `` 라는 구문이 나오면 +이 부분에 당신의 베이스 디렉터리를 대입하면 된다. + +{{< note>}} +만약 쿠버네티스 구성 도구와 API 레퍼런스에 기여하고 싶다면, +[업스트림 코드에 기여하기 (영문)](/docs/contribute/generate-ref-docs/contribute-upstream) 를 참조한다. +{{< /note >}} + +## `update-imported-docs` 스크립트 개요 {#Overview-of-update-imported-docs} + +`update-imported-docs` 스크립트는 `/update-imported-docs/` +디렉터리에 존재한다. + +이 스크립트는 다음 레퍼런스를 생성한다. + +* 구성요소 및 도구 레퍼런스 페이지 +* `kubectl` 명령어 레퍼런스 +* 쿠버네티스 API 레퍼런스 + +`update-imported-docs` 스크립트는 쿠버네티스 소스코드로부터 레퍼런스 문서를 +생성한다. 스크립트가 실행되면 개발 머신의 `/tmp` 디렉터리 아래에 임시 디렉터리를 +생성하고, 이 임시 디렉터리 아래에 레퍼런스 문서 생성에 필요한 `kubernetes/kubernetes` 저장소와 +`kubernetes-sigs/reference-docs` 저장소를 클론하며, +`GOPATH` 환경 변수를 이 임시 디렉터리로 지정한다. +또한 이 스크립트는 다음의 환경 변수를 설정한다. + +* `K8S_RELEASE` +* `K8S_ROOT` +* `K8S_WEBROOT` + +스크립트가 정상적으로 실행되려면 인자 2개를 전달해야 한다. + +* 환경설정 YAML 파일 (`reference.yml`) +* 쿠버네티스 릴리스 버전 (예: `1.17`) + +환경설정 파일은 `generate-command` 라는 필드를 포함하는데, +이 필드에는 +`kubernetes-sigs/reference-docs/Makefile` 에 있는 Make 타겟들을 활용하여 빌드하는 일련의 과정이 명시되어 있다. +`K8S_RELEASE` 환경 변수는 릴리스 버전을 결정한다. + +`update-imported-docs` 스크립트는 다음의 과정을 수행한다. + +1. 환경설정 파일에 있는 관련 저장소를 클론한다. + 레퍼런스 문서 생성을 위해 + 기본적으로는 `kubernetes-sigs/reference-docs` 저장소를 클론하도록 되어 있다. +1. 클론한 안에서, 문서 생성에 필요한 사항을 준비하기 위한 명령어를 실행한 뒤, + HTML 파일과 마크다운 파일을 생성한다. +1. 생성된 HTML 파일과 마크다운 파일을 + 환경설정 파일에 명시된 규칙에 따라 `` 로 복사한다. +1. `kubectl`.md 에 있는 `kubectl` 명령어 링크들이 + `kubectl` 명령어 레퍼런스 페이지의 올바른 섹션으로 연결되도록 업데이트한다. + +생성된 파일이 `` 아래에 복사되었으면, +`kubernetes/website` 저장소로 [풀 리퀘스트를 생성](/ko/docs/contribute/new-content/open-a-pr/) +할 수 있다. + +## 환경설정 파일 형식 {#Configuration-file-format} + +각 환경설정 파일은 레퍼런스 생성을 위해 필요한 여러 저장소의 정보를 담을 수 있다. +필요한 경우, 환경설정 파일을 직접 수정하여 사용할 수도 있다. +또는, 다른 그룹의 문서를 임포트하기 위해 새로운 환경설정 파일을 작성할 수도 있다. +다음은 환경설정 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 +``` + +이 도구에 의해 처리될 단일 페이지 마크다운 문서는 +[문서 스타일 가이드](/docs/contribute/style/style-guide/)의 내용을 만족해야 한다. + +## reference.yml 환경설정 파일 다루기 {#Customizing-reference-yml} + +`/update-imported-docs/reference.yml` 환경설정 파일을 열어 수정할 수 있다. +레퍼런스 문서 생성을 위해 명령어들이 어떻게 사용되고 있는지 파악하지 못했다면, +`generate-command` 필드의 내용은 수정하지 말아야 한다. +대부분의 경우 `reference.yml` 을 직접 수정해야 할 필요는 없다. +때때로, 업스트림 소스코드 업데이트 때문에 이 환경설정 파일을 수정해야 할 수도 있다. +(예: Golang 버전 의존성, 서드파티 라이브러리 변경 등) +만약 스크립트 사용 시 빌드 문제가 있다면, +[쿠버네티스 슬랙의 #sig-docs 채널](https://kubernetes.slack.com/archives/C1J0BPD2M)에서 SIG-Docs 팀에 문의하면 된다. + +{{< note >}} +`generate-command` 는 특정 저장소로부터 문서를 만들기 위한 +명령어나 스크립트를 실행하기 위해 사용할 수 있는 선택적 필드이다. +{{< /note >}} + +`reference.yml` 환경설정 파일에서, `files` 필드는 `src` 와 `dst` 필드를 포함한다. +`src` 필드에는 `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` 디렉터리로 많은 파일이 복사되어야 한다면, +`src` 필드에 와일드카드를 사용할 수 있다. +이 경우, `dst` 필드에는 단일 파일의 경로가 아니라 디렉터리의 경로를 명시해야 한다. +예시는 다음과 같다. + +```yaml + files: + - src: gen-compdocs/build/kubeadm*.md + dst: content/en/docs/reference/setup-tools/kubeadm/generated/ +``` + +## `update-imported-docs` 도구 실행하기 {#Running-the-update-imported-docs-tool} + +다음과 같이 `update-imported-docs` 도구를 실행할 수 있다. + +```shell +cd /update-imported-docs +./update-imported-docs +``` + +예를 들면 다음과 같다. + +```shell +./update-imported-docs reference.yml 1.17 +``` + + +## 링크 업데이트하기 {#Fixing-Links} + +`release.yml` 환경설정 파일은 상대경로 링크를 수정하는 방법을 포함하고 있다. +임포트하는 파일 안에 있는 상대경로 링크를 수정하려면, `gen-absolute-links` 필드를 +`true` 로 명시한다. 이에 대한 예시는 +[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml) 에서 볼 수 있다. + +## `kubernetes/website` 의 변경사항을 커밋하기 {#Adding-and-committing-changes-in-kubernetes-website} + +다음의 명령을 실행하여, 스크립트에 의해 생성된 뒤 `` 아래에 복사된 파일의 목록을 볼 수 있다. + +```shell +cd +git status +``` + +위의 명령을 실행하면 새로 추가된 파일과 수정된 파일의 목록을 볼 수 있다. +아래의 결과 예시는 업스트림 소스코드의 변경사항에 따라 다르게 나타날 수 있다. + +### 생성된 구성요소 도구 레퍼런스 {#Generated-component-tool-files} + +``` +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 명령어 레퍼런스 {#Generated-kubectl-command-reference-files} + +``` +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 레퍼런스 와 파일 {#Generated-Kubernetes-API-reference-directories-and-files} + +``` +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/query.scrollTo.min.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2 +``` + +`git add` 와 `git commit` 명령을 실행하여 추가/변경된 파일을 커밋한다. + +## 풀 리퀘스트 만들기 {#Creating-a-pull-request} + +`kubernetes/website` 저장소에 풀 리퀘스트를 등록한다. +등록한 풀 리퀘스트를 모니터하고, 리뷰 커멘트가 달리면 그에 대해 대응을 한다. +풀 리퀘스트가 머지될 때 까지 계속 모니터한다. + +풀 리퀘스트가 머지된 뒤 몇 분이 지나면, +변경사항을 +[쿠버네티스 문서 홈페이지](/docs/home/)에서 확인할 수 있다. + + + +## {{% heading "whatsnext" %}} + + +수동으로 빌드 저장소를 설정하고 빌드 타겟을 실행하여 개별 레퍼런스 문서를 생성하려면, +다음의 가이드를 참고한다. + +* [쿠버네티스 구성요소와 도구에 대한 레퍼런스 문서 생성하기](/docs/contribute/generate-ref-docs/kubernetes-components/) +* [kubectl 명령어에 대한 레퍼런스 문서 생성하기](/docs/contribute/generate-ref-docs/kubectl/) +* [쿠버네티스 API에 대한 레퍼런스 문서 생성하기](/docs/contribute/generate-ref-docs/kubernetes-api/) + +