Generowanie materiałów źródłowych dla polecenia kubectl

Ta strona pokazuje, jak wygenerować materiały źródłowe polecenia kubectl.

Zanim zaczniesz

Wymagania:

  • Potrzebujesz maszyny z systemem operacyjnym Linux lub macOS.

  • Musisz mieć zainstalowane następujące narzędzia:

    • Python w wersji 3.7.x+
    • Git - Dokumentacja opisuje, jak zainstalować i rozpocząć pracę z systemem kontroli wersji Git.
    • Golang wersja 1.13+
    • Pip używany do instalacji PyYAML
    • PyYAML w wersji 5.1.2
    • make
    • gcc compiler/linker
    • Docker (Wymagany tylko do odniesień do poleceń kubectl)

  • Twoja zmienna środowiskowa PATH musi zawierać wymagane narzędzia do budowania, takie jak binaria Go i python.

  • Musisz wiedzieć, jak utworzyć pull requesta do repozytorium na GitHubie. Wymaga to utworzenia własnego forka repozytorium. Aby uzyskać więcej informacji, zobacz Praca z lokalnej kopii.

Skonfiguruj lokalne repozytoria

Utwórz lokalną przestrzeń roboczą i ustaw swoje GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Utwórz lokalną kopię następujących repozytoriów:

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs

Jeśli nie masz jeszcze repozytorium kubernetes/website, pobierz je teraz:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Zrób klon repozytorium kubernetes/kubernetes jako k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

Usuń pakiet spf13 z $GOPATH/src/k8s.io/kubernetes/vendor/github.com:

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

Repozytorium kubernetes/kubernetes dostarcza kod źródłowy kubectl oraz kustomize.

  • Określ katalog bazowy twojej kopii repozytorium kubernetes/kubernetes. Na przykład, jeśli postępowałeś zgodnie z poprzednim krokiem, aby pobrać repozytorium, twój katalog bazowy to $GOPATH/src/k8s.io/kubernetes. Kolejne kroki odwołują się do twojego katalogu bazowego jako <k8s-base>.

  • Określ katalog bazowy klonu Twojego repozytorium kubernetes/website. Na przykład, jeśli wykonałeś poprzedni krok, aby pobrać repozytorium, Twoim katalogiem bazowym jest $GOPATH/src/github.com/<your-username>/website. Kolejne kroki odnoszą się do Twojego katalogu bazowego jako <web-base>.

  • Określ katalog główny dla Twojej kopii repozytorium kubernetes-sigs/reference-docs. Na przykład, jeśli postępowałeś zgodnie z poprzednim krokiem, aby uzyskać repozytorium, Twoim katalogiem głównym będzie $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Dalsze kroki odnoszą się do Twojego katalogu głównego jako <rdocs-base>.

W swoim lokalnym repozytorium k8s.io/kubernetes przejdź do interesującej Cię gałęzi i upewnij się, że jest ona aktualna. Na przykład, jeśli chcesz wygenerować dokumentację dla Kubernetesa 1.31.0, możesz użyć tych poleceń:

cd <k8s-base>
git checkout v1.31.0
git pull https://github.com/kubernetes/kubernetes 1.31.0

Jeśli nie musisz edytować kodu źródłowego kubectl, postępuj zgodnie z instrukcjami dotyczącymi Ustawiania zmiennych kompilacji.

Edytowanie kodu źródłowego kubectl

Materiały źródłowe polecenia kubectl są automatycznie generowana z kodu źródłowego kubectl. Jeśli chcesz zmienić materiały źródłowe, pierwszym krokiem jest zmiana jednego lub więcej komentarzy w kodzie źródłowym kubectl. Wprowadź zmianę w swoim lokalnym repozytorium kubernetes/kubernetes, a następnie zgłoś pull requesta do gałęzi master na github.com/kubernetes/kubernetes.

PR 56673 jest przykładem pull requesta, który poprawia literówkę w kodzie źródłowym kubectl.

Monitoruj swój pull request (PR) i odpowiadaj na komentarze recenzentów. Kontynuuj monitorowanie swojego PR, aż zostanie scalony z docelową gałęzią w repozytorium kubernetes/kubernetes.

Zrób cherry pick do gałęzi wydania

Twoja zmiana znajduje się teraz w głównej gałęzi, która jest używana do rozwoju następnego wydania Kubernetesa. Jeśli chcesz, aby twoja zmiana pojawiła się w wersji dokumentacji Kubernetesa, która została już wydana, musisz zaproponować włączenie twojej zmiany do gałęzi wydania.

Na przykład, załóżmy, że gałąź master jest używana do rozwijania Kubernetes 1.32 i chcesz przenieść swoją zmianę do gałęzi release-1.31. Aby uzyskać instrukcje, jak to zrobić, zobacz Proponowanie Cherry Pick.

Monitoruj swój cherry pick pull request, aż zostanie scalone z gałęzią wydania.

Ustaw zmienne budowania

Przejdź do <rdocs-base>. W swoim wierszu poleceń ustaw następujące zmienne środowiskowe.

  • Ustaw K8S_ROOT na <k8s-base>.
  • Ustaw K8S_WEBROOT na <web-base>.
  • Ustaw K8S_RELEASE na wersję dokumentacji, którą chcesz zbudować. Na przykład, jeśli chcesz zbudować dokumentację dla Kubernetesa 1.31, ustaw K8S_RELEASE na 1.31.

Na przykład:

export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.31

Tworzenie katalogu wersjonowanego

Uruchomienie budowania (ang. build target) createversiondirs tworzy katalog z wersjonowaniem i kopiuje pliki konfiguracyjne kubectl dotyczące materiałów źródłowych do tego katalogu. Nazwa katalogu z wersjonowaniem jest zgodna z wzorcem v<major>_<minor>.

W katalogu <rdocs-base>, uruchom następujący cel budowania:

cd <rdocs-base>
make createversiondirs

Sprawdź tag wydania w k8s.io/kubernetes

W swoim lokalnym repozytorium <k8s-base>, przejdź do gałęzi, która zawiera wersję Kubernetesa, którą chcesz udokumentować. Na przykład, jeśli chcesz wygenerować dokumentację dla Kubernetesa 1.31.0, przejdź do tagu v1.31. Upewnij się, że Twoja lokalna gałąź jest aktualna.

cd <k8s-base>
git checkout v1.31.0
git pull https://github.com/kubernetes/kubernetes v1.31.0

Uruchom kod generowania dokumentacji

W lokalnym katalogu <rdocs-base>, uruchom cel budowania (ang. build target) copycli. Komenda działa z uprawnieniami root:

cd <rdocs-base>
make copycli

Polecenie copycli czyści tymczasowy katalog kompilacji, generuje pliki poleceń kubectl i kopiuje zbiorczą stronę HTML materiałów źródłowych poleceń kubectl oraz zasoby do <web-base>.

Zlokalizuj wygenerowane pliki

Zweryfikuj, czy te dwa pliki zostały wygenerowane:

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

Zlokalizuj skopiowane pliki

Zweryfikuj, czy wszystkie wygenerowane pliki zostały skopiowane do Twojego <web-base>:

cd <web-base>
git status

Wynik powinien zawierać zmodyfikowane pliki:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

Wynik może również zawierać:

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/node_modules/font-awesome/css/font-awesome.min.css

Lokalne testowanie dokumentacji

Zbuduj dokumentację Kubernetes w lokalnym <web-base>.

cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve

Zobacz podgląd lokalny.

Dodaj i zatwierdź zmiany w kubernetes/website

Uruchom git add i git commit, aby zatwierdzić pliki.

Utwórz pull requesta

Utwórz pull requesta do repozytorium kubernetes/website. Monitoruj swój pull request i odpowiadaj na komentarze z przeglądu. Kontynuuj monitorowanie swojego pull requesta aż do momentu jego włączenia do głównej gałęzi kodu.

Kilka minut po włączeniu twojego pull requesta, zaktualizowane tematy materiałów źródłowych będą widoczne w opublikowanej dokumentacji.

Co dalej?

Ostatnia modyfikacja February 13, 2025 at 8:30 AM PST: [pl] docs/contribute/generate-ref-docs/kubectl.md (c0fd50a237)