# Budowanie dokumentacji w TeamCity

Build `Dokumentacja workspace` w projekcie `NARZĘDZIA / TOOLS` buduje całą stronę dokumentacji i wysyła ją na Cloudflare Pages. Cała logika siedzi w jednym skrypcie, `ci/docs.sh`.

## Jak to działa

Build ma jeden krok, który uruchamia `ci/docs.sh`. Skrypt klonuje repozytoria z `repos.txt`, instaluje narzędzia z `ci/requirements.txt` i woła `scripts/ws docs build`. Na końcu wysyła katalog `.site/` do projektu Cloudflare Pages `logintegra-docs`.

O adresie strony decyduje branch:

| Branch | Adres |
| --- | --- |
| `main` | `https://logintegra-docs.pages.dev` |
| każdy inny | `https://<branch>.logintegra-docs.pages.dev` |

Adres podglądu pojawia się w statusie buildu w TeamCity. Status buildu trafia też do pull requesta w Bitbuckecie.

Build startuje po każdym pushu do `logintegra-workspace` oraz co noc na `main`. Nocny build zbiera zmiany w dokumentacji pozostałych repozytoriów.

Poza `main` skrypt pomija dokumentację generowaną z `docs.toml`, bo specyfikacja OpenAPI wymaga JDK i buildu Gradle. Linki do niej nie działają więc na podglądach.

## Uruchomienie lokalnie

```
ci/docs.sh
```

Bez zmiennej `CF_PROJECT` skrypt tylko buduje `.site/` i niczego nie wysyła.

## Co zmieniać i gdzie

| Zmiana | Miejsce |
| --- | --- |
| nowe repozytorium z dokumentacją | wpis w `repos.txt` |
| wersja Zensical albo PyYAML | `ci/requirements.txt` |
| wersja Wranglera | `WRANGLER_VERSION` w `ci/docs.sh` |
| wersja Node dla Wranglera | `ci/.nvmrc` |
| projekt Cloudflare, harmonogram, agent | `WorkspaceDocs.kt` w `teamcity-configuration-as-a-code` |

## Wymagania

Projekt Cloudflare Pages `logintegra-docs` ma `main` jako branch produkcyjny. Cloudflare Access obejmuje adres produkcyjny i adresy podglądów, bo dokumentacja zawiera adresy wewnętrznych serwerów. Build używa testowego tokenu Cloudflare, tego samego co dokumentacja Apollo na środowisku testowym.

Agent TeamCity potrzebuje `python3`, `nvm` oraz JDK 11 dla specyfikacji OpenAPI. Node w wersji z `ci/.nvmrc` build instaluje sam przez `nvm install`. Repozytoria klonuje kluczem SSH `BitBucket Repo Access`.
