# Генерація документації для API Kubernetes

LLMS index: [llms.txt](/llms.txt)

---

<!-- 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).

Якщо ви знайшли помилки у згенерованій документації, вам потрібно [виправити їх на upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).

Якщо вам потрібно тільки згенерувати документацію з [OpenAPI](https://github.com/OAI/OpenAPI-Specification), продовжте читати цю сторінку.

## Перш ніж ви розпочнете


	<h3 id="prerequisites">Вимоги:<a class="td-heading-self-link" href="#prerequisites" aria-label="Heading self-link"></a></h3>
<ul>
<li>
<p>Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте <a href="https://learn.microsoft.com/en-us/windows/wsl/install">Підсистема Windows для Linux (WSL)</a>, оскільки інструменти збірки покладаються на <code>make</code> та Bash-скрипти.</p>
</li>
<li>
<p>Вам потрібно встановити ці інструменти:</p>
<ul>
<li><a href="https://git-scm.com/book/en/v2/Getting-Started-Installing-Git">Git</a></li>
<li><a href="https://go.dev/dl/">Go</a>, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)</li>
<li><a href="https://www.gnu.org/software/make/">make</a></li>
<li><a href="https://gcc.gnu.org/">gcc компілятор/лінкер</a></li>
<li><a href="https://docs.docker.com/engine/installation/">Docker</a> (Потрібен тільки для локального перегляду вебсайту за допомогою <code>make container-serve</code>)</li>
</ul>
</li>
<li>
<p>Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться <a href="/uk/docs/contribute/new-content/open-a-pr/#fork-the-repo">Робота з локальним клоном</a>.</p>
</li>
</ul>


<!-- steps -->

## Налаштування локальних репозиторіїв

Створіть локальне робоче середовище і встановіть ваш `GOPATH`:

```shell
mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>
```

Отримайте локальну копію наступних репозиторіїв:

```shell
git clone github.com/kubernetes-sigs/reference-docs
```

Перейдіть до теки `gen-apidocs` репозиторію `reference-docs` та встановіть необхідні пакунки Go:

```shell
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
```

Якщо у вас ще немає репозиторію kubernetes/website, отримайте його зараз:

```shell
git clone https://github.com/<your-username>/website
```

Отримайте копію репозиторію kubernetes/kubernetes:

```shell
git clone https://github.com/kubernetes/kubernetes
```

* Основна тека вашої копії [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) репозиторію є `<your-path-to>/kubernetes/kubernetes`. Подальші кроки використовують цю основну директорію як `<k8s-base>`.

* Основна тека вашої копії [kubernetes/website](https://github.com/kubernetes/website) репозиторію є `<your-path-to>/website`. Подальші кроки використовують цю основну директорію як `<web-base>`.

* Основна тека вашої копії [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) репозиторію є `<your-path-to>/reference-docs`. Подальші кроки використовують цю основну директорію як `<rdocs-base>`.

## Генерація документації API {#generate-the-api-reference-docs}

Цей розділ демонструє, як згенерувати [опубліковану документацію API Kubernetes](/docs/reference/generated/kubernetes-api/v1.36/).

### Встановлення змінних для зборки {#set-build-variables}

* Встановіть `K8S_ROOT` на `<k8s-base>`.
* Встановіть `K8S_WEBROOT` на `<web-base>`.
* Встановіть `K8S_RELEASE` на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.17.0, встановіть `K8S_RELEASE` на 1.17.0.

Наприклад:

```shell
export K8S_WEBROOT=<your-path-to>/website
export K8S_ROOT=<your-path-to>/kubernetes
export K8S_RELEASE=1.17.0
```

### Створення теки версії та завантаження специфікації Open API {#create-versioned-directory-and-fetch-open-api-spec}

Ціль збірки `updateapispec` створює теку версії для збірки. Після створення теки, специфікація Open API завантажується з репозиторію `<k8s-base>`. Ці кроки забезпечують відповідність версій конфігураційних файлів і Kubernetes Open API специфікації з версією релізу. Назва теки версії слідує шаблону `v<major>_<minor>`.

У теці `<rdocs-base>`, виконайте наступну ціль збірки:

```shell
cd <rdocs-base>
make updateapispec
```

### Збірка документації API {#build-the-api-reference-docs}

Ціль `copyapi` будує документацію API та копіює згенеровані файли до теки у `<web-base>`. Виконайте наступну команду у `<rdocs-base>`:

```shell
cd <rdocs-base>
make copyapi
```

Перевірте, що ці два файли були згенеровані:

```shell
[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
```

Перейдіть до основної теки вашого локального `<web-base>`, і перегляньте, які файли були змінені:

```shell
cd <web-base>
git status
```

Вихідний результат буде подібним до:

```none
static/docs/reference/generated/kubernetes-api/v1.36/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.36/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.36/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.36/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.36/index.html
static/docs/reference/generated/kubernetes-api/v1.36/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.36/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.36/js/scroll.js
```

## Розташування та версії довідки API {#api-reference-location-and-versioning}

Створені файли довідки API (версія HTML) копіюються в `<web-base>/static/docs/reference/generated/kubernetes-api/v1.36/`. Ця тека містить автономну документацію API у форматі HTML.


<div class="alert alert-info" role="note"><h4 class="alert-heading">Примітка:</h4>Markdown-версія довідки API, розташована в <code>&lt;web-base&gt;/content/en/docs/reference/kubernetes-api/</code>, генерується окремо за допомогою генератора <a href="https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs">gen-resourcesdocs</a>.</div>


## Локальне тестування документації API {#locally-test-the-api-reference}

Опублікуйте локальну версію документації API. Перевірте [локальний попередній перегляд](/docs/reference/generated/kubernetes-api/v1.36/).

```shell
cd <web-base>
git submodule update --init --recursive --depth 1 # якщо ще не зроблено
make container-serve
```

## Коміт змін {#commit-the-changes}

У `<web-base>`, виконайте `git add` і `git commit`, щоб зафіксувати зміни.

Подайте ваші зміни як [pull request](/docs/contribute/new-content/open-a-pr/) до репозиторію [kubernetes/website](https://github.com/kubernetes/website). Слідкуйте за вашим pull request, і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

## Що далі

* [Швидкий старт з генерації документації](/docs/contribute/generate-ref-docs/quickstart/)
* [Генерація документації для компонентів та інструментів Kubernetes](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Генерація документації для команд kubectl](/docs/contribute/generate-ref-docs/kubectl/)