207 lines
9.5 KiB
Markdown
207 lines
9.5 KiB
Markdown
---
|
||
title: Génération de pages de référence pour les composants et les outils Kubernetes
|
||
content_type: task
|
||
---
|
||
|
||
<!-- overview -->
|
||
|
||
Cette page montre comment utiliser l'outil `update-importer-docs` pour générer une documentation de référence pour les outils et les composants des dépôts [Kubernetes](https://github.com/kubernetes/kubernetes) et [Federation](https://github.com/kubernetes/federation).
|
||
|
||
|
||
|
||
## {{% heading "prerequisites" %}}
|
||
|
||
|
||
* Vous avez besoin d'une machine qui exécute Linux ou macOS.
|
||
|
||
* Ces logiciels doivent être installés:
|
||
|
||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||
|
||
* [Golang](https://golang.org/doc/install) version 1.13 ou ultérieure
|
||
|
||
* [make](https://www.gnu.org/software/make/)
|
||
|
||
* [gcc compiler/linker](https://gcc.gnu.org/)
|
||
|
||
* Votre variable d'environnement `$GOPATH` doit être définie.
|
||
|
||
* Vous devez savoir comment créer une pull request sur un dépôt GitHub.
|
||
Cela implique généralement la création d’un fork d'un dépôt.
|
||
Pour plus d'informations, consultez [Créer une Pull Request de documentation](/docs/home/contribute/create-pull-request/).
|
||
|
||
|
||
|
||
<!-- steps -->
|
||
|
||
## Obtenir deux dépôts
|
||
|
||
Si vous n'avez pas déjà le dépôt `kubernetes/website`, obtenez le maintenant:
|
||
|
||
```shell
|
||
mkdir $GOPATH/src
|
||
cd $GOPATH/src
|
||
go get github.com/kubernetes/website
|
||
```
|
||
|
||
Déterminez le répertoire de base de votre clone du dépôt [kubernetes/website](https://github.com/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 envisagez d’apporter des modifications aux documents de référence et si vous ne disposez pas déjà du dépôt `kubernetes/kubernetes`, obtenez-le maintenant:
|
||
|
||
```shell
|
||
mkdir $GOPATH/src
|
||
cd $GOPATH/src
|
||
go get github.com/kubernetes/kubernetes
|
||
```
|
||
|
||
Déterminez le répertoire de base de votre clone du dépôt [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
||
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/kubernetes`.
|
||
Les étapes restantes se réfèrent à votre répertoire de base en tant que `<k8s-base>`.
|
||
|
||
{{< note >}}
|
||
Si vous devez uniquement générer, sans modifier, les documents de référence, vous n'avez pas besoin d'obtenir manuellement le dépôt `kubernetes/kubernetes`.
|
||
Lorsque vous exécutez la commande `update-imported-docs`, il clone automatiquement le dépôt `kubernetes/kubernetes`.
|
||
{{< /note >}}
|
||
|
||
## Modification du code source de Kubernetes
|
||
|
||
La documentation de référence pour les composants et les outils Kubernetes est générée automatiquement à partir du code source de Kubernetes.
|
||
Si vous souhaitez modifier la documentation de référence, commencez par modifier un ou plusieurs commentaires dans le code source de Kubernetes.
|
||
Faites le changement dans votre dépôt local `kubernetes/kubernetes`, puis soumettez une pull request sur la branche master [github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
||
|
||
[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942) est un exemple de pull request qui modifie les commentaires dans le code source de Kubernetes.
|
||
|
||
Surveillez votre pull request, et répondez aux commentaires des relecteurs.
|
||
Continuez à surveiller votre pull request jusqu'à ce qu'elle soit mergée dans la branche master du dépot `kubernetes/kubernetes`.
|
||
|
||
## Selectionnez vos commits dans une branche release
|
||
|
||
Vos commits sont sur la branche master, qui est utilisée pour le développement sur la prochaine sortie de Kubernetes.
|
||
Si vous souhaitez que vos commits apparaissent dans la documentation d'une version Kubernetes déjà publiée, vous devez proposer que vos commits soit sélectionnée dans la branche de publication.
|
||
|
||
Par exemple, supposons que la branche master est utilisée pour développer Kubernetes 1.10, et vous voulez transférer vos commits sur la branche release-1.9.
|
||
Pour savoir comment faire cela, consultez [Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-release/cherry-picks.md).
|
||
|
||
Surveillez votre pull request cherry-pick jusqu'à ce qu'elle soit mergée dans la branche release.
|
||
|
||
{{< note >}}
|
||
Proposer un cherry pick exige que vous ayez la permission de définir un label et un milestone dans votre pull request.
|
||
Si vous ne disposez pas de ces autorisations, vous devrez travailler avec une personne pouvant définir les paramètres de labels et de milestone pour vous.
|
||
{{< /note >}}
|
||
|
||
## Vue générale de update-imported-docs
|
||
|
||
L'outil `update-importer-docs` se trouve dans le répertoire `kubernetes/website/update-importer-docs/`.
|
||
L'outil effectue les étapes suivantes:
|
||
|
||
1. Effectuez un clone des différents dépots spéciés dans le fichier de configuration.
|
||
Afin de générer des documents de référence, les dépôts clonés par défaut sont: `kubernetes-incubator/reference-docs` et `kubernetes/federation`.
|
||
1. Effectuez les commandes dans les dépôts clonés pour préparer le générateur de documentation et génerer les fichiers Markdown.
|
||
1. Copiez les fichiers markdown générés dans un copie locale du dépôt `kubernetes/website`. Les fichiers doivent être mis dans les dossiers spécifiés dans le fichier de configuration.
|
||
|
||
Quand les fichiers Markdown sont dans votre clone local du dépot `kubernetes/website`, vous pouvez les soumettre dans une [pull request](/docs/home/contribute/create-pull-request/) vers `kubernetes/website`.
|
||
|
||
## Personnaliser le fichier de configuration
|
||
|
||
Ouvrez `<web-base>/update-importer-docs/reference.yml` pour le modifier.
|
||
Ne modifiez pas le contenu de l'entrée `generate-command` sauf si vous comprenez ce qu'elle fait et devez modifier la branche de release spécifiée.
|
||
|
||
```shell
|
||
repos:
|
||
- name: reference-docs
|
||
remote: https://github.com/kubernetes-incubator/reference-docs.git
|
||
# Ceci et la commande generate ci-dessous nécessitent une modification lorsque les branches de référence-docs sont correctement définies
|
||
branch: master
|
||
generate-command: |
|
||
cd $GOPATH
|
||
git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
|
||
cd src/k8s.io/kubernetes
|
||
git checkout release-1.11
|
||
make generated_files
|
||
cp -L -R vendor $GOPATH/src
|
||
rm -r vendor
|
||
cd $GOPATH
|
||
go get -v github.com/kubernetes-incubator/reference-docs/gen-compdocs
|
||
cd src/github.com/kubernetes-incubator/reference-docs/
|
||
make comp
|
||
```
|
||
|
||
Dans reference.yml, les attributs `files` est une liste d'objets ayant des attributs `src` et `dst`.
|
||
L'attribut `src` spécifie l'emplacement d'un fichier Markdown généré, et l'attribut `dst` spécifie où copier ce fichier dans le dépôt local `kubernetes/website`.
|
||
Par exemple:
|
||
|
||
```yaml
|
||
repos:
|
||
- name: reference-docs
|
||
remote: https://github.com/kubernetes-incubator/reference-docs.git
|
||
files:
|
||
- src: gen-compdocs/build/kube-apiserver.md
|
||
dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||
...
|
||
```
|
||
|
||
Notez que lorsqu'il y a beaucoup de fichiers à copier du même répertoire source dans le même répertoire de destination, vous pouvez utiliser des caractères génériques dans la valeur donnée à `src` et vous pouvez simplement fournir le nom du répertoire comme valeur pour `dst`.
|
||
Par exemple:
|
||
|
||
```shell
|
||
files:
|
||
- src: gen-compdocs/build/kubeadm*.md
|
||
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
|
||
```
|
||
|
||
## Exécution de l'outil update-importer-docs
|
||
|
||
Après avoir revu et/ou personnalisé le fichier `reference.yaml`, vous pouvez exécuter l'outil `update-imports-docs`:
|
||
|
||
```shell
|
||
cd <web-base>/update-imported-docs
|
||
./update-imported-docs reference.yml
|
||
```
|
||
|
||
## Ajouter et valider des modifications dans kubernetes/website
|
||
|
||
Répertoriez les fichiers générés et copiés dans le dépôt `kubernetes/website`:
|
||
|
||
```
|
||
cd <web-base>
|
||
git status
|
||
```
|
||
|
||
La sortie affiche les fichiers nouveaux et modifiés.
|
||
Par exemple, la sortie pourrait ressembler à ceci:
|
||
|
||
```shell
|
||
...
|
||
|
||
modified: content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
|
||
modified: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md
|
||
modified: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md
|
||
modified: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||
modified: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
|
||
modified: content/en/docs/reference/command-line-tools-reference/kube-proxy.md
|
||
modified: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
|
||
...
|
||
```
|
||
|
||
Exécutez `git add` et `git commit` pour faire un commit de ces fichiers.
|
||
|
||
## Créer une pull request
|
||
|
||
Créez une pull request vers le dépôt `kubernetes/website`.
|
||
Consultez votre pull request et répondez aux corrections suggérées par les rélecteurs jusqu'à ce que la pull request soit acceptée et mergée.
|
||
|
||
Quelques minutes après le merge votre pull request, vos références mises à jour seront visibles dans la [documentation publiée](/docs/home/).
|
||
|
||
|
||
|
||
## {{% heading "whatsnext" %}}
|
||
|
||
|
||
* [Génération de documentation de référence pour les commandes kubectl](/docs/home/contribute/generated-reference/kubectl/)
|
||
* [Génération de documentation de référence pour l'API Kubernetes](/fr/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||
* [Génération de documentation de référence pour l'API de fédération Kubernetes](/docs/home/contribute/generated-reference/federation-api/)
|
||
|
||
|