Génération de documentation de référence pour l'API Kubernetes
Cette page montre comment mettre à jour les documents de référence générés automatiquement pour l'API Kubernetes.
Pré-requis
Vous devez avoir ces outils installés:
Votre variable d'environnement $GOPATH doit être définie et l'emplacement de etcd doit être dans votre variable d'environnement $PATH.
Vous devez savoir comment créer une pull request dans un dépôt GitHub. Généralement, cela implique la création d'un fork du dépôt. Pour plus d'informations, voir Créer une Pull Request de documentation et GitHub Standard Fork & Pull Request Workflow.
Généralités
La mise à jour de la documentation de référence de l'API Kubernetes est un processus en deux étapes:
-
Générez une spécification OpenAPI à partir du code source de Kubernetes. Les outils pour cette étape sont kubernetes/kubernetes/hack.
-
Générez un fichier HTML à partir de la spécification OpenAPI. Les outils pour cette étape sont à kubernetes-incubator/reference-docs.
Obtenir trois dépôts
Si vous ne possédez pas déjà le dépôt kubernetes/kubernetes, téléchargez-le maintenant:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
Déterminez le dépôt de base de votre clone de kubernetes/kubernetes.
Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre dépôt de base est $GOPATH/src/github.com/kubernetes/kubernetes.
Les étapes restantes se réfèrent à votre répertoire de base en tant que <k8s-base>.
Si vous ne possédez pas déjà le dépôt kubernetes/website, obtenez-le maintenant:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
Déterminez le répertoire de base de votre dépôt kubernetes/website.
Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre répertoire de base est $GOPATH/src/github.com/kubernetes/website.
Les étapes restantes se réfèrent à votre répertoire de base en tant que <web-base>.
Si vous n'avez pas déjà le dépôt kubernetes-incubator/reference-docs, obtenez-le maintenant:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
Déterminez le répertoire de base de votre dépôt kubernetes-incubator/reference-docs.
Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre répertoire de base est $GOPATH/src/github.com/kubernetes-incubator/reference-docs.
Les étapes restantes se réfèrent à votre répertoire de base en tant que <rdocs-base>.
Modification du code source de Kubernetes
La documentation de référence de l'API Kubernetes est générée automatiquement à partir d'une spécification OpenAPI, générée à partir du code source de Kubernetes. Si vous souhaitez modifier la documentation de référence, la première étape consiste à modifier un ou plusieurs commentaires dans le code source de Kubernetes.
Modification des commentaires dans le code source
Voici un exemple d'édition d'un commentaire dans le code source de Kubernetes.
Dans votre dépôt local kubernetes/kubernetes, vérifiez la branche master et assurez-vous qu'elle est à jour:
cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master
Supposons que ce fichier source dans la branche principale ait la typo "atmost":
kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go
Dans votre environnement local, ouvrez types.go et remplacez "atmost" par "at most".
Vérifiez que vous avez modifié le fichier:
git status
La sortie montre que vous êtes sur la branche master et que le fichier source types.go a été modifié:
On branch master
...
modified: staging/src/k8s.io/api/apps/v1/types.go
Valider votre fichier édité
Exécutez git add et git commit pour valider les modifications que vous avez apportées jusqu'à présent.
Dans l'étape suivante, vous ferez un deuxième commit.
Il est important de séparer vos modifications en deux commits.
Génération de la spécification OpenAPI et des fichiers associés
Allez sur <k8s-base> et exécutez ces scripts:
hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
Exécutez git status pour voir ce qui a été généré.
On branch master
...
modified: api/openapi-spec/swagger.json
modified: staging/src/k8s.io/api/apps/v1/generated.proto
modified: staging/src/k8s.io/api/apps/v1/types.go
modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go
Voir le contenu de api/openapi-spec/swagger.json pour vous assurer que la faute de frappe est corrigée.
Par exemple, vous pouvez exécuter git diff -a api/openapi-spec/swagger.json.
Ceci est important, car swagger.json sera l’entrée de la seconde étape du processus de génération de doc.
Exécutez git add et git commit pour valider vos modifications.
Vous avez maintenant deux validations: une avec le fichier types.go édité et une avec les spécifications OpenAPI générées et les fichiers associés.
Gardez ces deux commits séparés.
C'est-à-dire, ne faites pas un squash de vos commits.
Soumettez vos modifications en tant que pull request à la branche principale du dépôt kubernetes/kubernetes. Surveillez votre pull request, et répondre aux commentaires des relecteurs au besoin. Continuez à surveiller votre pull request jusqu'à ce qu'il ait été mergé.
PR 57758 est un exemple de demande d'extraction qui corrige une faute de frappe dans le code source de Kubernetes.
staging du dépôt kubernetes/kubernetes.
Mais dans votre cas, le répertoire staging pourrait ne pas être l’endroit où trouver la source faisant autorité.
Pour vous guider, consultez les fichiers README dans le dépôt kubernetes/kubernetes et dans le dépôt kubernetes/apiserver.
Cherry picking votre commit dans une branche release
Dans la section précédente, vous avez modifié un fichier dans la branche principale, puis exécuté des scripts pour générer une spécification OpenAPI et les fichiers associés.
Vous avez ensuite soumis vos modifications dans une demande d'extraction à la branche maître du dépôt kubernetes/kubernetes.
Supposons maintenant que vous souhaitiez faire un backport de votre modification dans une branche de publication.
Par exemple, supposons que la branche principale soit utilisée pour développer Kubernetes version 1.10 et que vous souhaitiez faire un backport de votre modification dans la branche de la version 1.9.
Rappelez-vous que votre pull request a deux commits: un pour l'édition types.go et un pour les fichiers générés par des scripts.
La prochaine étape consiste à proposer un cherry pick de votre premier commit dans la branche release-1.9.
L'idée est de cherry pick le commit qui a édité types.go, mais pas le commit qui a pour résultat l'exécution des scripts.
Pour les instructions, voir Proposer un Cherry Pick.
Quand vous avez une pull request en place pour cherry picking votre seul commit dans la branche release-1.9, l’étape suivante consiste à exécuter ces scripts dans la branche release-1.9 de votre environnement local.
hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh
Maintenant, ajoutez un commit à votre cherry-pick pull request qui contient la spécification OpenAPI récemment générée et les fichiers associés. Surveillez votre pull request jusqu'à ce qu'elle soit mergée dans la branche release-1.9.
À ce stade, la branche master et la branche release-1.9 ont votre fichier types.go mis à jour et un ensemble de fichiers générés qui reflètent les modifications apportées à types.go.
Notez que la spécification OpenAPI générée et les autres fichiers générés dans la branche release-1.9 ne sont pas nécessairement identiques aux fichiers générés dans la branche master.
Les fichiers générés dans la branche release-1.9 contiennent des éléments API uniquement à partir de Kubernetes 1.9.
Les fichiers générés dans la branche maître peuvent contenir des éléments de l'API qui ne sont pas dans la version 1.9, mais sont en cours de développement pour la version 1.10.
Génération des documents de référence publiés
La section précédente a montré comment modifier un fichier source, puis générer plusieurs fichiers, y compris api/openapi-spec/swagger.json dans le dépôt kubernetes/kubernetes.
Cette section montre comment générer la documentation de référence de l'API Kubernetes publiée, qui est générée par les outils de kubernetes-incubator/reference-docs.
Ces outils prennent le fichier api/openapi-spec/swagger.json comme entrée.
Modification du Makefile dans kubernetes-incubator/reference-docs
Aller à <rdocs-base>, et ouvrez Makefile pour l'édition:
Définissez K8SROOT dans le répertoire de base de votre dépôt local kubernetes/kubernetes.
Définissez WEBROOT sur le répertoire de base de votre référentiel kubernetes/website.
Définissez MINOR_VERSION sur la version mineure de la documentation que vous souhaitez créer.
Par exemple, si vous souhaitez créer des documents pour Kubernetes 1.9, définissez MINOR_VERSION sur 9.
Enregistrez et fermez Makefile.
Copier la spécification OpenAPI
Le code de génération de document nécessite une copie locale de la spécification OpenAPI pour l'API Kubernetes.
Allez sur <k8s-base> et vérifiez la branche qui a la spécification OpenAPI que vous voulez utiliser.
Par exemple, si vous souhaitez générer des documents pour Kubernetes 1.9, consultez la branche release-1.9.
Retournez à <rdocs-base>.
Entrez la commande suivante pour copier la spécification OpenAPI à partir du dépôt kubernetes/kubernetes vers un répertoire local:
make updateapispec
La sortie montre que le fichier a été copié:
cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
Construire l'image brodocs
Le code de génération de doc nécessite l'image Docker pwittrock/brodocs.
Cette commande crée l’image Docker pwittrock/brodocs.
Il essaie également de transmettre l’image à DockerHub, mais c’est acceptable si cette étape échoue.
Tant que vous avez l'image localement, la génération de code peut réussir.
make brodocs
Vérifiez que vous avez l'image brodocs:
docker images
La sortie affiche pwittrock / brodocs comme l'une des images disponibles:
REPOSITORY TAG IMAGE ID CREATED SIZE
pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB
Exécuter le code de génération de doc
Générez et exécutez le code de génération de doc. Vous devrez peut-être exécuter la commande en tant que root:
cd <rdocs-base>
make api
Localiser les fichiers générés
Ces deux fichiers sont le résultat d’une construction réussie. Vérifiez qu'ils existent:
<rdocs-base>/gen-apidocs/generators/build/index.html<rdocs-base>/gen-apidocs/generators/build/navData.js
Copier les documents générés dans le dépôt kubernetes/website
Les sections précédentes ont montré comment modifier un fichier source Kubernetes, générer une spécification OpenAPI, puis générer une documentation de référence pour la publication.
Cette section explique comment copier les documents générés sur le dépôt kubernetes/website.
Les fichiers dans le dépôt kubernetes/website sont publiés sur le site web kubernetes.io.
En particulier, le fichier généré index.html est publié ici.
Entrez la commande suivante pour copier les fichiers générés dans votre dépôt local kubernetes/website:
make copyapi
Allez à la base de votre dépôt local kubernetes/kubernetes, et regardez quels fichiers ont été modifiés:
cd <web-base>
git status
La sortie montre les fichiers modifiés:
On branch master
...
modified: docs/reference/generated/kubernetes-api/v1.9/index.html
Dans cet exemple, un seul fichier a été modifié.
Rappelez-vous que vous avez généré les deux index.html et navData.js.
Mais apparemment le généré navata.js n'est pas différent du navData.js c'était déjà dans le dépôt kubernetes/website.
Dans <web-base> executez git add et git commit pour enregistrer le commit du changement.
Soumettez vos modifications en tant que pull request au dépôt kubernetes/website. Surveillez votre pull request, et répondez aux commentaires des relecteurs au besoin. Continuez à surveiller votre pull request jusqu'à ce qu'elle ait été mergée.
Quelques minutes après que votre pull request soit fusionnée, vos modifications seront visibles dans la documentation de référence publiée.