Contribuer à la documentation Kubernetes

• 1: Commencez à contribuer
• 2: Contributions avancées
• 3: Aperçu du style de documentation
• 3.1: Documentation Style Guide
• 3.2: Rédiger une nouveau sujet
• 3.3: Utilisation des modèles de page
• 3.4: Organisation du contenu
• 3.5: Hugo Shortcodes personnalisés
• 4: Vue d'ensemble des documents de référence
• 4.1: Génération de documentation de référence pour l'API Kubernetes
• 4.2: Génération de la documentation de référence pour l'API de fédération Kubernetes
• 4.3: Génération de pages de référence pour les composants et les outils Kubernetes
• 5: Participez au SIG Docs
• 6: Traduction de la documentation Kubernetes

1 - Commencez à contribuer

Si vous souhaitez commencer à contribuer à la documentation de Kubernetes, cette page et les rubriques associées peuvent vous aider à démarrer. Vous n'avez pas besoin d'être un développeur ou un rédacteur technique pour avoir un impact important sur la documentation et l'expérience utilisateur de Kubernetes ! Tout ce dont vous avez besoin pour les sujets de cette page est un compte GitHub et un navigateur web.

Si vous recherchez des informations sur la façon de commencer à contribuer aux référentiels de code Kubernetes, reportez-vous à la section sur les directives de la communauté Kubernetes.

Les bases de notre documentation

La documentation de Kubernetes est écrite en Markdown puis traitée et déployée à l’aide de Hugo. Le code source est sur GitHub: https://github.com/kubernetes/website. La majeure partie de la documentation anglaise est stockée dans /content/en/docs/. Une partie de la documentation de référence est automatiquement générée à partir de scripts du répertoire update-imported-docs/.

Vous pouvez trier les demandes, modifier le contenu et passer en revue les modifications des autres, le tout à partir du site Web de GitHub. Vous pouvez également utiliser l'historique intégré et les outils de recherche de GitHub.

Toutes les tâches ne peuvent pas être effectuées dans l’interface utilisateur GitHub, mais elles sont décrites dans les guides de contribution intermédiaire et avancé.

Participer à SIG Docs

La documentation de Kubernetes est gérée par un groupe d'intérêt spécial (Special Interest Group (SIG)) appelé SIG Docs. Nous communiquons via un canal Slack, une liste de diffusion et des réunions vidéo hebdomadaires. Les nouveaux participants sont les bienvenus. Pour plus d'informations, voir Participer au SIG-docs.

Guides de style

Nous maintenons un guide de style avec des informations sur les choix de la communauté SIG Docs concernant la grammaire, la syntaxe, le format des sources et les conventions typographiques. Avant de faire votre première contribution, parcourez le guide de style et utilisez-le lorsque vous avez des questions.

Les modifications apportées au guide de style sont effectuées par SIG Docs en tant que groupe. Pour proposer un changement ou un ajout, ajoutez-le à l'ordre du jour pour une réunion à venir sur les documents SIG et assister à la réunion pour participer à la discussion. Voir le sujet contribution avancée pour plus d'informations.

Modèle de page

Nous utilisons des modèles de page pour contrôler la présentation de nos pages de documentation. Assurez-vous de comprendre le fonctionnement de ces modèles en consultant Utilisation de modèles de page.

Shortcodes Hugo

La documentation de Kubernetes est convertie de Markdown à HTML avec Hugo. Nous utilisons les shortcodes standard Hugo, ainsi que quelques-uns qui sont personnalisés dans la documentation Kubernetes. Voyez "Shortcodes Hugo personnalisés" pour savoir comment les utiliser.

Multilingue

La source de la documentation est disponible en plusieurs langues dans /content/. Chaque langue a son propre dossier avec un code à deux lettres déterminé par le standard ISO 639-1. Par exemple, la source de la documentation anglaise est stockée dans /content/en/docs/.

Pour plus d'informations sur la contribution à la documentation dans plusieurs langues, consultez "Traduire le contenu" dans le guide de contribution intermédiaire.

Si vous souhaitez démarrer une nouvelle traduction, voir "Traduction".

Créer des demandes recevables

Toute personne possédant un compte GitHub peut soumettre un problème (rapport de bogue) à la documentation de Kubernetes. Si vous voyez quelque chose qui ne va pas, même si vous ne savez pas comment le réparer, ouvrez un ticket. L'exception à cette règle est un petit bug, comme une faute de frappe, que vous souhaitez réparer vous-même. Dans ce cas, vous pouvez plutôt le réparer sans déposer un bogue d'abord.

Comment ouvrir un ticket

• Sur une page existante

  Si vous voyez un problème dans une page existante de la documentation Kubernetes, allez au bas de la page et cliquez sur le bouton Create an Issue. Si vous n'êtes pas actuellement connecté à GitHub, connectez-vous. Un formulaire de ticket GitHub apparaît avec du contenu pré-rempli.

  À l’aide de Markdown, renseignez autant de détails que possible. Aux endroits où vous voyez des crochets vides ([ ]), mettre un x entre les crochets qui représente le choix approprié. Si vous avez une solution proposée pour résoudre le problème, ajoutez-la.

• Demander une nouvelle page

  Si vous pensez que du contenu est manquant, mais que vous ne savez pas où il doit aller ou si vous pensez qu'il ne correspond pas aux pages existantes, vous pouvez toujours ouvrir un ticket. Vous pouvez soit choisir une page existante à proximité du lieu où le nouveau contenu doit aller et classer le problème à partir de cette page, soit aller directement à https://github.com/kubernetes/website/issues/new/ et déposer le problème à partir de là.

Comment créer de bons tickets

Pour nous assurer que nous comprenons votre problème et pouvons y donner suite, gardez à l’esprit ces directives:

• Utilisez le modèle de ticket et renseignez autant de détails que possible.

• Expliquez clairement l’impact spécifique du problème sur les utilisateurs.

• Limiter la portée d'un problème à une unité de travail raisonnable. Pour les problèmes de grande envergure, décomposez-les en problèmes plus petits.

  Par exemple, "Corriger les docs de sécurité" n'est pas une question pouvant donner lieu à une action, mais "Ajouter des détails au thème 'Restreindre l'accès au réseau'" pourrait l'être.

• Si la demande concerne un autre problème ou une pull request, vous pouvez y faire référence soit par son URL complète, soit par le problème ou par un numéro de demande d'extraction précédé du caractère "#". Par exemple, Introduced by #987654.

• Soyez respectueux et restez constructif. Par exemple, "La documentation sur X est nulle" n'est ni utile ni constructif. Le Code de conduite s'applique également aux interactions sur les dépôts Kubernetes GitHub.

Participer aux discussions SIG Docs

L'équipe SIG Docs communique à l'aide des mécanismes suivants:

• Rejoindre l'instance Slack de Kubernetes, puis rejoignez le canal #sig-docs, où nous discutons des problèmes de documentation en temps réel. Présentez-vous quand vous arrivez!
• Rejoignez la liste de diffusion kubernetes-sig-docs, où des discussions plus larges ont lieu et où les décisions officielles sont enregistrées.
• Participer à l'hebdomadaire SIG Docs, une réunion vidéo, qui est annoncée sur le canal Slack et la liste de diffusion. Actuellement, ces réunions ont lieu sur Zoom. Vous devez donc télécharger le logiciel Zoom ou rejoindre la conférence par téléphone.
• Pour les utilisateurs francophones, vous pouvez également rejoindre le canal Slack #kubernetes-docs-fr, où nous discutons des traductions en Français de la documentation de Kubernetes.

Améliorer le contenu existant

Pour améliorer le contenu existant, vous déposez une pull request (PR) après avoir créé un fork. Ces deux termes sont spécifiques à GitHub. Pour les besoins de cette rubrique, vous n'avez pas besoin de tout savoir à leur sujet, car vous pouvez tout faire à l'aide de votre navigateur Web. Quand vous passerez au Guide des contributeurs docs intermédiaires, vous aurez besoin de plus de connaissances en terminologie Git.

Signer le CLA

Avant de pouvoir apporter du code ou de la documentation à Kubernetes, vous devez lire le Guide du contributeur et signer le Contributor License Agreement (CLA). Ne vous inquiétez pas, cela ne prend pas longtemps !

Trouvez quelque chose sur lequel travailler

Si vous voyez quelque chose que vous souhaitez réparer immédiatement, suivez simplement les instructions ci-dessous. Vous n'avez pas besoin d'ouvrir un ticket (bien que vous puissiez aussi).

Si vous souhaitez commencer par trouver un problème existant sur lequel travailler, allez à https://github.com/kubernetes/website/issues et chercher des problèmes avec le label good first issue (vous pouvez utiliser ce raccourci). Lisez tous les commentaires et assurez-vous qu’il n’y a pas de pull request existante pour ce même problème et que personne n’a laissé de commentaire indiquant qu’ils travaillent sur le problème récemment (une durée de 3 jours est une bonne règle). Laissez un commentaire indiquant que vous souhaitez travailler sur la question.

Choisissez quelle branche Git utiliser

L'aspect le plus important de la soumission d'une pull request c'est choisir la branche sur laquelle baser votre travail. Utilisez ces directives pour prendre la décision:

• Utilisez master pour résoudre les problèmes de contenu déjà publié ou pour améliorer le contenu déjà existant.
  • Utiliser une branche de publication (tel que dev-release-1.23 pour le release-1.23 release) pour documenter les fonctionnalités ou modifications à venir pour une version à venir non encore publiée.
• Utilisez une branche de fonctionnalités approuvée par SIG Docs pour collaborer à de grandes améliorations ou modifications de la documentation existante, y compris la réorganisation du contenu ou des modifications apportées à l'apparence du site Web.

Si vous ne savez toujours pas quelle branche choisir, demandez #sig-docs sur Slack ou assistez à une réunion hebdomadaire de documents SIG pour obtenir des précisions.

Soumettre une pull request

Suivez ces étapes pour soumettre une pull request afin d'améliorer la documentation de Kubernetes.

1. Sur la page où vous voyez le problème, cliquez sur l'icône en forme de crayon en haut à gauche. Une nouvelle page apparaît avec un texte d'aide.

2. Cliquez sur le premier bouton bleu, qui a le texte Edit <page name>.

   Si vous n'avez jamais créé de fork du dépôt de documentation Kubernetes, vous êtes invité à le faire. Créez le fork sous votre nom d'utilisateur GitHub, plutôt que celui d'une autre organisation dont vous pourriez être membre. Le fork a généralement une URL telle que https://github.com/<nom d'utilisateur>/website, à moins que vous n'ayez déjà un dépôt avec un nom en conflit (website).

   La raison pour laquelle vous êtes invité à créer un fork est que vous n'avez pas le droit de pousser une branche directement vers le dépôt Kubernetes officiel.

3. L'éditeur GitHub Markdown apparaît avec le fichier source Markdown chargé. Faites vos changements. Sous l'éditeur, remplissez le formulaire Propose file change. Le premier champ est le résumé de votre message de validation et ne doit pas dépasser 50 caractères. Le deuxième champ est facultatif, mais peut inclure plus de détails si nécessaire.

   Note: Ne pas inclure de références à d’autres demandes GitHub ou pull requests dans votre message de commit. Vous pouvez les ajouter ultérieurement à la description de la demande d'extraction.

   Cliquez sur Propose file change. La modification est enregistrée en tant que commit dans une nouvelle branche de votre fork, qui porte automatiquement le nom suivant: patch-1.

4. L’écran suivant récapitule les modifications que vous avez apportées en comparant votre nouvelle branche (les boîtes de sélection head fork et compare) à l'état actuel de base fork et base branche (master sur le dépôt kubernetes/website par défaut). Vous pouvez modifier n'importe quelle boîte de sélection, mais ne le faites pas maintenant. Jetez un coup d’œil à la visionneuse de différences en bas de l’écran et, si tout se présente bien, cliquez sur Create pull request.

   Note: Si vous ne voulez pas créer la pull request maintenant, vous pouvez le faire plus tard, en accédant à l'URL principale du référentiel de site Web Kubernetes ou du référentiel de votre fork. Le site Web GitHub vous invitera à créer la pull request s'il détecte que vous avez poussé une nouvelle branche vers votre fork.

5. L'écran Open a pull request apparaît. Le sujet de la pull request est identique au message du commit, mais vous pouvez le modifier si nécessaire. Le corps est rempli par le reste du message du commit (s'il est présent) et par un modèle. Lisez le modèle et remplissez les informations demandées, puis supprimez le texte supplémentaire. Laissez la case à cocher sélectionnée Allow edits from maintainers. Cliquez sur Create pull request.

   Toutes nos félicitations ! Votre pull request est disponible dans Pull requests.

   Après quelques minutes, vous pouvez prévisualiser le site Web contenant les modifications apportées par votre PR. Aller sur l'onglet Conversation de votre PR et cliquez sur le lien Details pour le déploiement deploy/netlify, près du bas de la page. Il s'ouvrira dans la même fenêtre.

6. Attendez la revue. En général, les relecteurs sont suggérés par le k8s-ci-robot. Si un relecteur vous demande d’apporter des modifications, vous pouvez aller à l'onglet Files changed et cliquez sur l'icône en forme de crayon sur les fichiers modifiés par la pull request. Lorsque vous enregistrez le fichier modifié, un nouveau commit est créé dans la branche surveillée par la pull request.

7. Si votre modification est acceptée, un relecteur fusionnera votre pull request, et le changement sera visible sur le site Web de Kubernetes quelques minutes plus tard.

Ce n’est qu’un des différents moyens de soumettre une pull request. Si vous êtes déjà un utilisateur expérimenté de Git et GitHub, vous pouvez utiliser une interface graphique locale ou un client Git en ligne de commande au lieu d'utiliser l'interface utilisateur de GitHub. Quelques notions de base sur l’utilisation du client Git en ligne de commande sont abordées dans la section intermédiaire du guide des contributeurs.

Relecture des pull requests de documentation

Les personnes qui ne sont pas encore des approbateurs ou des relecteurs peuvent quand même relire des pull requests. Leurs avis ne font pas autorité, ce qui signifie que ces avis seuls ne causeront pas une fusion de la pull request. Cependant, cela peut toujours être utile. Même si vous ne laissez aucun commentaire, vous pourrez avoir une idée des conventions des pull requests, de l'étiquette des interactions entre les différents membres et ainsi vous habituer au processus.

1. Allez à https://github.com/kubernetes/website/pulls. Vous verrez une liste de toutes les pull requests ouvertes visant site web Kubernetes et la documentation.

2. Par défaut, le seul filtre appliqué est open, donc vous ne voyez pas les pull requests qui ont déjà été fermées ou fusionnées. C'est une bonne idée d'appliquer le filtre cncf-cla: yes, et pour votre premier examen, c'est une bonne idée d'ajouter size/S ou size/XS. Le label size est appliqué automatiquement en fonction du nombre de lignes de code que la PR modifie. Vous pouvez appliquer des filtres en utilisation les boites de sélection en haut de la page, ou utilisez directement ce raccourci pour voir seulement les petites PRs. Tous les filtres sont combinés (opérateur AND), de sorte que vous ne pouvez pas rechercher size/XS et size/S dans la même requête.

3. Allez à l'onglet Files changed. Parcourez les modifications introduites dans la PR et, le cas échéant, les problèmes liés. Si vous constatez un problème ou des améliorations à apporter, passez la souris sur la ligne et cliquez sur le symbole + qui apparaît.

   Vous pouvez taper un commentaire et choisir soit Add single comment ou Start a review. En règle générale, il est préférable de commencer une revue, car elle vous permet de laisser plusieurs commentaires et d’avertir le propriétaire de la PR uniquement lorsque vous avez terminé la revue, plutôt qu'envoyer une notification distincte pour chaque commentaire.

4. Lorsque vous avez terminé, cliquez sur Review changes en haut de la page. Vous pouvez résumer votre avis et choisir de commenter, approuver ou demander des modifications. Les nouveaux contributeurs doivent toujours choisir Comment.

Merci d'avoir commenté une pull request ! Lorsque vous débutez dans le projet, il est judicieux de demander votre avis sur votre pull request. Le canal Slack #sig-docs est un excellent endroit pour faire cela.

Écrire un article dans le blog

Tout le monde peut écrire un article et le soumettre pour examen. Les articles ne doivent pas être de nature commerciale et doivent comporter un contenu qui s’appliquera de manière large à la communauté Kubernetes.

Pour soumettre un article, vous pouvez soit le soumettre en utilisant le Formulaire de soumission de blog Kubernetes, soit en suivant les étapes ci-dessous :

1. Signez le CLA si vous ne l'avez pas encore fait.
2. Consultez le format Markdown pour les articles de blog existants dans le dépôt du site web.
3. Rédigez votre article dans l'éditeur de texte de votre choix.
4. Sur le même lien à partir de l'étape 2, cliquez sur le bouton Create new file. Collez votre contenu dans l'éditeur. Nommez le fichier pour qu'il corresponde au titre proposé de l'article, mais ne mettez pas la date dans le nom du fichier. Les réviseurs de blog travailleront avec vous sur le nom de fichier final et la date de publication du blog.
5. Lorsque vous enregistrez le fichier, GitHub vous guidera à travers le processus d'une pull request.
6. Un critique de publication de blog examinera votre soumission et travaillera avec vous sur les commentaires et les détails finaux. Lorsque l'article du blog est approuvé, la publication du blog est planifiée.

Soumettre une étude de cas

Des études de cas montrent comment les entreprises utilisent Kubernetes pour résoudre des problèmes concrets. Elles sont écrites en collaboration avec l'équipe marketing de Kubernetes, qui est gérée par la CNCF.

Regardez la source des études de cas existantes. Utilisez le Formulaire de soumission d'étude de cas Kubernetes pour soumettre votre proposition.

A suivre

Si vous êtes à l'aise avec toutes les tâches décrites dans cette rubrique et que vous souhaitez vous engager plus profondément dans l'équipe de documentation de Kubernetes, lisez le guide de contribution de la documentation intermédiaire.

2 - Contributions avancées

Cette page suppose que vous avez lu et maîtrisé les sujets suivants : Commencez à contribuer et Contribution Intermédiaire et êtes prêts à apprendre plus de façons de contribuer. Vous devez utiliser Git et d'autres outils pour certaines de ces tâches.

Soyez le trieur de PR pendant une semaine

Les approbateurs SIG Docs peuvent être trieurs de Pull Request (PR).

Les approbateurs SIG Docs sont ajoutés au PR Wrangler rotation scheduler pour les rotations hebdomadaires. Les fonctions de trieur de PR incluent:

• Faire une revue quotidienne des nouvelles pull requests.
  • Aidez les nouveaux contributeurs à signer le CLA et fermez toutes les PR où le CLA n'a pas été signé depuis deux semaines. Les auteurs de PR peuvent rouvrir la PR après avoir signé le CLA, c’est donc un moyen à faible risque de s’assurer que rien n’est merged sans un CLA signé.
  • Fournir des informations sur les modifications proposées, notamment en facilitant les examens techniques des membres d'autres SIGs.
  • Faire un merge des PRs quand elles sont prêtes, ou fermer celles qui ne devraient pas être acceptées.
• Triez et étiquetez les tickets entrants (Github Issues) chaque jour. Consultez Contributions Intermédiaires pour obtenir des instructions sur la manière dont SIG Docs utilise les métadonnées.

Requêtes Github utiles pour les trieurs

Les requêtes suivantes sont utiles lors des opérations de triage. Après avoir utilisé ces trois requêtes, la liste restante de PRs devant être examinées est généralement petite. Ces requêtes excluent spécifiquement les PRs de localisation, et n'incluent que la branche master (sauf la derniere).

• Pas de CLA, non éligible au merge: Rappelez au contributeur de signer le CLA. S’ils ont déjà été rappelés à la fois par le bot et par un humain, fermez la PR et rappelez-leur qu'ils peuvent l'ouvrir après avoir signé le CLA. Nous ne pouvons même pas passer en revue les PR dont les auteurs n'ont pas signé le CLA !
• A besoin de LGTM: Si cela nécessite une révision technique, contactez l'un des réviseurs proposés par le bot. Si cela nécessite une révision de la documentation ou une édition, vous pouvez soit suggérer des modifications, soit ajouter un commit d'édition à la PR pour la faire avancer.
• A des LGTM, a besoin de docs approval: Voyez si vous pouvez comprendre ce qui doit se passer pour que la PR soit mergée.
• Not against master: Si c'est basé sur une branche dev-, c'est pour une release prochaine. Assurez vous que le release meister est au courant. Si elle se base sur une branche obsolète, aidez l'auteur de la PR à comprendre comment choisir la meilleure branche.

Proposer des améliorations

Les membres SIG Docs peuvent proposer des améliorations.

Après avoir contribué à la documentation de Kubernetes pendant un certain temps, vous pouvez avoir des idées pour améliorer le guide de style, les outils utilisés pour construire la documentation, le style du site, les processus de révision et faire un merge de pull requests, ou d'autres aspects de la documentation. Pour une transparence maximale, ces types de propositions doivent être discutées lors d’une réunion SIG Docs ou sur la liste de diffusion kubernetes-sig-docs. En outre, il peut être vraiment utile de situer le fonctionnement actuel et de déterminer les raisons pour lesquelles des décisions antérieures ont été prises avant de proposer des changements radicaux. Le moyen le plus rapide d’obtenir des réponses aux questions sur le fonctionnement actuel de la documentation est de le demander dans le canal #sig-docs sur le Slack officiel kubernetes.slack.com

Une fois que la discussion a eu lieu et que le SIG est d'accord sur le résultat souhaité, vous pouvez travailler sur les modifications proposées de la manière la plus appropriée. Par exemple, une mise à jour du guide de style ou du fonctionnement du site Web peut impliquer l’ouverture d’une pull request, une modification liée aux tests de documentation peut impliquer de travailler avec sig-testing.

Coordonner la documentation pour une version de Kubernetes

Les approbateurs SIG Docs peuvent coordonner les tâches liées à la documentation pour une release de Kubernetes.

Chaque release de Kubernetes est coordonnée par une équipe de personnes participant au sig-release Special Interest Group (SIG). Les autres membres de l'équipe de publication pour une release donnée incluent un responsable général de la publication, ainsi que des représentants de sig-pm, de sig-testing et d'autres. Pour en savoir plus sur les processus de release de Kubernetes, reportez-vous à la section https://github.com/kubernetes/sig-release.

Le représentant de SIG Docs pour une release donnée coordonne les tâches suivantes:

• Surveillez le feature-tracking spreadsheet pour les fonctionnalités nouvelles ou modifiées ayant un impact sur la documentation. Si la documentation pour une fonctionnalité donnée ne sera pas prête pour la release, la fonctionnalité peut ne pas être autorisée à entrer dans la release.
• Assistez régulièrement aux réunions de sig-release et donnez des mises à jour sur l'état de la documentation pour la release.
• Consultez et copiez la documentation de la fonctionnalité rédigée par le SIG responsable de la mise en œuvre de la fonctionnalité.
• Mergez les pull requests liées à la release et maintenir la branche de fonctionnalité Git pour la version.
• Encadrez d'autres contributeurs SIG Docs qui souhaitent apprendre à jouer ce rôle à l'avenir.   Ceci est connu comme "l'observation" (shadowing en anglais).
• Publiez les modifications de la documentation relatives à la version lorsque les artefacts de la version sont publiés.

La coordination d'une publication est généralement un engagement de 3 à 4 mois et les tâches sont alternées entre les approbateurs SIG Docs.

Parrainez un nouveau contributeur

Les relecteurs SIG Docs peuvent parrainer de nouveaux contributeurs.

Après que les nouveaux contributeurs aient soumis avec succès 5 pull requests significatives vers un ou plusieurs dépôts Kubernetes, ils/elles sont éligibles pour postuler à l'adhésion dans l'organisation Kubernetes. L'adhésion des contributeurs doit être soutenue par deux sponsors qui sont déjà des réviseurs.

Les nouveaux contributeurs docs peuvent demander des sponsors dans le canal #sig-docs sur le Slack Kubernetes ou sur la mailing list SIG Docs. Si vous vous sentez confiant dans le travail des candidats, vous vous portez volontaire pour les parrainer. Lorsqu’ils soumettent leur demande d’adhésion, répondez-y avec un "+1" et indiquez les raisons pour lesquelles vous estimez que les demandeurs sont des candidat(e)s valables pour devenir membre de l’organisation Kubernetes.

3 - Aperçu du style de documentation

Les rubriques de cette section fournissent des informations sur le style d'écriture, la mise en forme et l'organisation du contenu, ainsi que sur l'utilisation des personnalisations Hugo spécifiques à la documentation Kubernetes.

3.1 - Documentation Style Guide

Cette page donne des directives de style d'écriture pour la documentation de Kubernetes. Ce sont des lignes directrices, pas des règles. Faites preuve de discernement et n'hésitez pas à proposer des modifications à ce document dans le cadre d'une pull request.

Pour plus d'informations sur la création de nouveau contenu pour les documents Kubernetes, suivez les instructions surl'utilisation des templates et création d'une pull request de documentation.

Language

La documentation de Kubernetes utilise l'anglais américain comme langue de référence.

Normes de formatage de la documentation

Utilisez le camel case pour les objets d'API

Lorsque vous faites référence à un objet API, utilisez les mêmes lettres majuscules et minuscules que celles utilisées dans le nom d'objet réel. Typiquement, les noms des objets de l'API utilisent le camel case.

Ne divisez pas le nom de l'objet API en mots séparés. Par exemple, utilisez PodTemplateList, et pas Pod Template List.

Référez-vous aux objets de l'API sans dire "objet", à moins que l'omission de "objet" n'entraîne une construction maladroite.

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents.

1. Affiche des informations sur un Pod :

   kubectl describe pod <pod-name>
   

   where <pod-name> is the name of one of your Pods.

Use bold for user interface elements

Utiliser l'italique pour définir ou introduire de nouveaux termes.

Utiliser un style de code pour les noms de fichiers, les répertoires et les chemins d'accès

Utiliser la norme internationale pour la ponctuation entre guillemets

Inline code formatting

Use code style for inline code and commands

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).

Utiliser le style de code pour les noms de champs d'objets

Utiliser le style normal pour les chaînes de caractères et les valeurs de champs entiers

Pour les valeurs de champ de type chaîne de caractères ou entier, utilisez un style normal sans guillemets.

Code snippet formatting

Ne pas inclure l'invite de commande

Séparer les commandes de la sortie

Vérifiez que le Pod fonctionne sur le nœud que vous avez choisi :

kubectl get pods --output=wide

La sortie est similaire à celle-ci :

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Versioning Kubernetes examples

Code examples and configuration examples that include version information should be consistent with the accompanying text.

If the information is version specific, the Kubernetes version needs to be defined in the prerequisites section of the Task template or the [Tutorial template] (/docs/contribute/style/page-templates/#tutorial-template). Once the page is saved, the prerequisites section is shown as Before you begin.

Pour spécifier la version de Kubernetes pour une tâche ou une page de tutoriel, incluez min-kubernetes-server-version dans l'entête de la page.

Si l'exemple YAML se trouve dans un fichier autonome, recherchez et passez en revue les sujets qui l'incluent comme référence. Vérifiez que toutes les rubriques utilisant le YAML autonome ont les informations de version appropriées définies. Si un fichier YAML autonome n'est référencé à partir d'aucun sujet, pensez à le supprimer au lieu de le mettre à jour.

Par exemple, si vous écrivez un tutoriel pertinent pour Kubernetes version 1.8, la première partie de votre fichier de démarque doit ressembler à ceci :

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

Dans les exemples de code et de configuration, n'incluez pas de commentaires sur les versions alternatives. Veillez à ne pas inclure d'énoncés incorrects dans vos exemples sous forme de commentaires, tels que :

apiVersion: v1 # earlier versions use...
kind: Pod
...

Liste de mots Kubernetes.io

Une liste de termes et de mots spécifiques à Kubernetes à utiliser de manière cohérente sur le site.

Shortcodes

Hugo Shortcodes help create different rhetorical appeal levels. Notre documentation prend en charge trois shortcodes différents dans cette catégorie : Note {{< note >}}, Mise en garde {{< caution >}}, et Avertissement {{< warning >}}.

1. Entourez le texte d'un raccourci d'ouverture et de fermeture.

2. Utilisez la syntaxe suivante pour appliquer un style :

   {{< note >}}
   Il n'est pas nécessaire d'inclure un préfixe ; le shortcode fournit automatiquement (Note:, Caution:, etc.).
   {{< /note >}}
   

La sortie est :

Note

Utilisez {{< note *//>}} pour mettre en surbrillance un conseil ou une information qu'il peut être utile de connaître.

Par exemple :

{{</* note >}}
Vous pouvez _toujours_ utiliser Markdown à l'intérieur de ces légendes.
{{< /note >}}

La sortie est :

Mise en garde

Utilisez {{< caution *//>}} pour attirer l'attention sur une information importante afin d'éviter les pièges.

Par exemple :

{{</* caution >}}
Le style de légende ne s'applique qu'à la ligne directement au-dessus de la balise.
{{< /caution >}}

La sortie est :

Avertissement

Utilisez {{< warning *//>}} pour indiquer un danger ou une information cruciale à suivre.

Par exemple :

{{</* warning >}}
Méfiez-vous.
{{< /warning >}}

La sortie est :

Katacoda Embedded Live Environment

Ce bouton permet aux utilisateurs d'exécuter Minikube dans leur navigateur en utilisant le Katacoda Terminal. Il abaisse le seuil d'entrée en permettant aux utilisateurs d'utiliser Minikube en un seul clic au lieu de passer par l'ensemble du processus d'installation Minikube et Kubectl localement.

The Embedded Live Environment is configured to run minikube start and lets users complete tutorials in the same window as the documentation.

For example:

{{< kat-button >}}

La sortie est :

Common Shortcode Issues

Ordered Lists

Un Shortcode interrompra les listes numérotées à moins que vous ne mettiez une indentation de 4 espaces avant l'avis et l'étiquette.

Par exemple :

1. Préchauffer le four à 350˚F

1. Préparer la pâte et la verser dans un moule à charnière.
   {{< note >}}**Note:** Graisser la casserole pour de meilleurs résultats.{{< /note >}}

1. Cuire au four de 20 à 25 minutes ou jusqu'à ce que ce soit pris.

La sortie est :

1. Préchauffer le four à 350˚F

2. Préparer la pâte et la verser dans un moule à charnière.

   Note: Graisser la casserole pour de meilleurs résultats.

3. Cuire au four de 20 à 25 minutes ou jusqu'à ce que ce soit pris.

Expressions Includes

Les Shortcodes dans les expressions d'include brisera la compilation du site. Vous devez les insérer dans le document parent, avant et après avoir appelé l'include. Par exemple :

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Meilleures pratiques en matière de contenu

Cette section contient des suggestions de pratiques exemplaires pour un contenu clair, concis et cohérent.

Utiliser le présent

Exception : Utilisez le futur ou le passé s'il est nécessaire pour transmettre le sens correct.

Utiliser la voix active

Exception : Utilisez la voix passive si la voix active conduit à une construction maladroite.

Utiliser un langage simple et direct

Utilisez un langage simple et direct. Évitez d'utiliser des expressions inutiles, comme "s'il vous plaît".

S'adresser au lecteur en tant que "vous"

Évitez les phrases latines

Préférez les termes français aux abréviations latines.

Exception : Utilisez "etc." pour et cetera.

Tendances à éviter

Évitez d'utiliser "nous"

L'utilisation du "nous" dans une phrase peut prêter à confusion, car le lecteur pourrait ne pas savoir s'ils font partie du "nous" que vous décrivez.

Évitez le jargon et les expressions idiomatiques

Certains lecteurs parlent le français comme seconde langue. Évitez le jargon et les expressions idiomatiques pour les aider à mieux comprendre.

Évitez les déclarations sur l'avenir

Évitez de faire des promesses ou de donner des conseils sur l'avenir. Si vous avez besoin de parler d'une fonctionnalité alpha, placez le texte sous un titre qui l'identifie comme une fonctionnalité alpha.

Évitez les déclarations qui seront bientôt périmées

Évitez les mots comme "actuellement" et "nouveau". Une caractéristique qui est nouvelle aujourd'hui pourrait ne pas être considérée comme nouvelle dans quelques mois.

A suivre

• En savoir plus sur writing a new topic.
• En savoir plus sur using page templates.
• En savoir plus sur staging your changes
• En savoir plus sur creating a pull request.

3.2 - Rédiger une nouveau sujet

Cette page montre comment créer un nouveau sujet pour la documentation Kubernetes.

Pré-requis

Créez un fork du dépôt de la documentation de Kubernetes comme décrit dans Commencez à contribuer.

Choisir un type de page

Alors que vous vous préparez à écrire un nouveau sujet, pensez au type de page qui convient le mieux à votre contenu :

Utilisez un modèle pour chaque nouvelle page. Chaque type de page a un template que vous pouvez utiliser lorsque vous écrivez votre sujet. L'utilisation de templates permet d'assurer la cohérence entre les sujets d'un type donné.

Choisir un titre et un nom de fichier

Choisissez un titre qui contient les mots-clés que vous voulez que les moteurs de recherche trouvent. Créez un nom de fichier qui utilise les mots de votre titre séparés par des tirets. Par exemple, le sujet avec titre Using an HTTP Proxy to Access the Kubernetes API has filename http-proxy-access-api.md. Vous n'avez pas besoin de mettre "kubernetes" dans le nom du fichier, car "kubernetes" est déjà dans l'URL du sujet, par exemple :

   /docs/tasks/access-kubernetes-api/http-proxy-access-api/

Ajout du titre du sujet à l'entête

Dans votre sujet, insérez un champ title dans l'entête frontmatter. L'entête est le bloc YAML qui se trouve entre les lignes à trois tirets en haut de la page. En voici un exemple :

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

Choisir un répertoire

En fonction de votre type de page, placez votre nouveau fichier dans un sous-répertoire de l'un d'entre eux :

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

Vous pouvez placer votre fichier dans un sous-répertoire existant ou en créer un nouveau.

Placer votre sujet dans la table des matières

La table des matières est construite dynamiquement en utilisant la structure de répertoire de la source de documentation. Les répertoires de niveau supérieur sous /content/fr/docs/ créent une navigation de niveau supérieur, et les sous-répertoires ont chacun des entrées dans la table des matières.

Chaque sous-répertoire possède un fichier _index.md, qui représente la page d'accueil du contenu d'un sous-répertoire donné. Le _index.md n'a pas besoin d'un template. Il peut contenir une vue d'ensemble du contenu des rubriques du sous-répertoire.

Les autres fichiers d'un répertoire sont triés par ordre alphabétique par défaut. Ce n'est presque jamais le meilleur ordre. Pour contrôler le tri relatif des sujets dans un sous-répertoire, définissez la clé weight: front-matter sur un entier. Généralement, nous utilisons des multiples de 10, pour tenir compte de l'ajout de sujets plus tard. Par exemple, un sujet ayant un poids de 10 sera précédé d'un sujet ayant un poids de 20.

Intégrer du code dans votre sujet

Si vous voulez inclure du code dans votre sujet, vous pouvez incorporer le code dans votre fichier directement à l'aide de l'option de syntaxe de bloc de code de markdown. Ceci est recommandé dans les cas suivants (liste non exhaustive) :

• Le code indique la sortie d'une commande telle que kubectl get deploy mydeployment -o json | jq '.status'.
• Le code n'est pas assez générique pour que les utilisateurs puissent l'essayer. Par exemple, vous pouvez intégrer le fichier YAML pour créer un Pod qui dépend d'une implementation Flexvolume spécifique.
• Le code est un exemple incomplet parce qu'il a pour but de mettre en évidence une partie d'un fichier plus volumineux. Par exemple, lorsque vous décrivez des façons de personnaliser l'attribut PodSecurityPolicy pour certaines raisons, vous pouvez fournir un court snippet directement dans le fichier.
• Le code n'est pas destiné à être testé par les utilisateurs pour d'autres raisons. Par exemple, lorsque vous décrivez comment un nouvel attribut doit être ajouté à une ressource à l'aide de la commande kubectl edit, vous pouvez fournir un court exemple qui inclut seulement l'attribut à ajouter.

Inclure le code d'un autre fichier

Une autre façon d'inclure du code dans votre sujet est de créer un nouveau fichier d'exemple complet (ou un groupe de fichiers d'exemple), puis de référencer l'exemple de votre sujet. Utilisez cette méthode pour inclure des exemples de fichiers YAML lorsque l'échantillon est générique et réutilisable, et que vous voulez favoriser leur utilisation.

Lors de l'ajout d'un nouveau fichier d'exemple autonome, tel qu'un fichier YAML, placez le code dans l'un des sous-répertoires <LANG>/examples/ où <LANG> est la langue utilisé dans votre page. Dans votre fichier, utilisez le shortcode codenew :

{{< codenew file="<RELPATH>/my-example-yaml>" >}}

où <RELPATH> est le chemin vers le fichier à inclure, relatif au répertoire examples. Le shortcode Hugo suivant fait référence à un fichier YAML situé sur /content/en/examples/pods/storage/gce-volume.yaml.

{{< codenew file="pods/storage/gce-volume.yaml" >}}

Montrer comment créer un objet API à partir d'un fichier de configuration

Si vous avez besoin de démontrer comment créer un objet API basé sur un fichier de configuration, placez le fichier de configuration dans l'un des sous-répertoires sous <LANG>/examples.

Dans votre sujet, affichez cette commande :

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

Pour un exemple d'un sujet qui utilise cette technique, voir Running a Single-Instance Stateful Application.

Ajouter des images à un sujet

Placez les fichiers images dans le répertoire /images. Le format d'image préféré est SVG.

A suivre

• En savoir plus sur l'utilisation des templates de pages.
• En savoir plus sur le staging de vos changements.
• En savoir plus sur la création d'une pull request.

3.3 - Utilisation des modèles de page

Lorsque vous ajoutez de nouveaux sujets, appliquez-leur l'un des templates suivants. Ceci standardise l'expérience utilisateur d'une page donnée.

Les templates de page sont dans le répertoire layouts/partials/templates du dépôt kubernetes/website.

Concept template

Une page de concept explique certains aspects de Kubernetes. Par exemple, une page conceptuelle peut décrire l'objet Kubernetes Deployment et expliquer le rôle qu'il joue en tant qu'application une fois qu'il est déployé, dimensionné et mis à jour. Généralement, les pages conceptuelles n'incluent pas de séquences d'étapes, mais fournissent plutôt des liens vers des tâches ou des tutoriels.

Pour écrire une nouvelle page concept, créez un fichier Markdown dans un sous-répertoire du répertoire /content/fr/docs/concepts, avec les caractéristiques suivantes :

• Dans l'entête YAML de la page, définissez content_type: concept.

• Dans le corps de la page, définissez les variables capture requises et les variables optionnelles que vous voulez inclure :

  Variable	Required?
  overview	yes
  body	yes
  whatsnext	no

  Le corps de la page ressemblera à ceci (supprimez toutes les captures optionnelles dont vous n'avez pas besoin) :

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture body %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Remplissez chaque section de contenu. Suivez ces lignes directrices :

  • Organiser le contenu avec les rubriques H2 et H3.
  • Pour overview, définir le contexte du sujet à l'aide d'un seul paragraphe.
  • Pour body, expliquer le concept.
  • Pour whatsnext, fournir une liste à puces de sujets (5 au maximum) pour en apprendre davantage sur le concept.

Annotations est un exemple publié du template de concept. Cette page utilise également le modèle de concept.

Template de tâche

Une page de tâches montre comment faire une seule chose, généralement en donnant une courte séquence d'étapes. Les pages de tâches ont une explication minimale, mais fournissent souvent des liens vers des sujets conceptuels qui fournissent un contexte et des connaissances connexes.

Pour écrire une nouvelle page de tâches, créez un fichier Markdown dans un sous-répertoire du répertoire /content/fr/docs/tasks, avec les caractéristiques suivantes :

• Dans l'entête YAML de la page, définissez content_type: task.

• Dans le corps de la page, définissez les variables capture requises et les variables optionnelles que vous voulez inclure :

  Variable	Required?
  overview	yes
  prerequisites	yes
  steps	no
  discussion	no
  whatsnext	no

  Le corps de la page ressemblera à ceci (supprimez toutes les captures optionnelles dont vous n'avez pas besoin) :

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture prerequisites %}}
  
  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  
  {{% /capture %}}
  
  {{% capture steps %}}
  
  {{% /capture %}}
  
  {{% capture discussion %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Dans chaque section, écrivez votre contenu. Suivez les directives suivantes :

  • Utilisez un minimum d'en-têtes H2 (avec deux caractères # en tête de liste). Les sections elles-mêmes sont intitulées automatiquement par le modèle.
  • Pour overview, utilisez un paragraphe pour définir le contexte de l'ensemble du sujet.
  • Pour prerequisites, utiliser des listes à puces dans la mesure du possible. Commencez à ajouter des prérequis supplémentaires sous la balise include. Les conditions préalables par défaut incluent un cluster Kubernetes en cours d'exécution.
  • Pour steps, utiliser des listes numérotées.
  • Pour la discussion, utilisez le contenu normal pour développer l'information couverte dans la section steps.
  • Pour whatsnext, donnez une liste de 5 sujets au maximum qui peuvent être intéressant à lire ensuite.

Voici un exemple de sujet publié qui utilise le template de tasks Using an HTTP proxy to access the Kubernetes API.

Tutorial template

Une page de tutoriel montre comment atteindre un objectif qui est plus grand qu'une seule tâche. Typiquement, une page de tutoriel comporte plusieurs sections, chacune d'entre elles ayant une séquence d'étapes. Par exemple, un tutoriel pourrait fournir un aperçu d'un exemple de code qui illustre une certaine caractéristique de Kubernetes. Les didacticiels peuvent inclure des explications au niveau de la surface, mais devraient être reliés à des sujets connexes sur les concepts pour des explications approfondies.

Pour écrire une nouvelle page de tutoriel, créez un fichier Markdown dans un sous-répertoire du répertoire /content/fr/docs/tutorials, avec les caractéristiques suivantes :

• Dans l'entête YAML de la page, définissez content_type: tutorial.

• Dans le corps de la page, définissez les variables capture requises et les variables optionnelles que vous voulez inclure :

  Variable	Required?
  overview	yes
  prerequisites	yes
  objectives	yes
  lessoncontent	yes
  cleanup	no
  whatsnext	no

  Le corps de la page ressemblera à ceci (supprimez toutes les captures optionnelles dont vous n'avez pas besoin) :

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture prerequisites %}}
  
  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  
  {{% /capture %}}
  
  {{% capture objectives %}}
  
  {{% /capture %}}
  
  {{% capture lessoncontent %}}
  
  {{% /capture %}}
  
  {{% capture cleanup %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Dans chaque section, écrivez votre contenu. Suivez les directives suivantes :

  • Utilisez un minimum d'en-têtes H2 (avec deux caractères # en tête de liste). Les sections elles-mêmes sont intitulées automatiquement par le template.
  • Pour overview, utiliser un paragraphe pour définir le contexte de l'ensemble du sujet.
  • Pour prerequisites, utiliser des listes à puces dans la mesure du possible. Ajoutez des prérequis supplémentaires en dessous de ceux inclus par défaut.
  • Pour objectives, utiliser des listes à puces.
  • Pour lessoncontent, utiliser un mélange de listes numérotées et de contenu narratif, le cas échéant.
  • Pour cleanup, utiliser des listes numérotées pour décrire les étapes de nettoyage de l'état du cluster une fois la tâche terminée.
  • Pour whatsnext, Donnez une liste de 5 sujets au maximum qu'il serait intéressant à lire ensuite.

Voici un exemple de sujet publié qui utilise le modèle de tutoriel Running a Stateless Application Using a Deployment.

A suivre

• En savoir plus sur le style guide
• En savoir plus sur l'organisation des contenus

3.4 - Organisation du contenu

Ce site utilise Hugo. Dans Hugo, l'organisation du contenu est un concept de base.

Listes de pages

Ordre des pages

Le menu latéral de la documentation, le navigateur de la page de documentation, etc. sont listés selon l'ordre de tri par défaut de Hugo, qui trie par poids (à partir de 1), par date (la plus récente en premier), et enfin par titre du lien.

Si vous voulez déplacer une page ou une section vers le haut, placez un poids dans l'entête de la page :

title: My Page
weight: 10

Menu principal de la documentation

Le menu principal Documentation est construit à partir des sections ci-dessous docs/ avec le drapeau main_menu placé dans l'entête du fichier de contenu de la section `_index.md' :

main_menu: true

Notez que le titre du lien est récupéré à partir du linkTitle de la page, donc si vous voulez qu'il soit différent du titre, changez-le dans le fichier du contenu cible :

main_menu: true
title: Page Title
linkTitle: Title used in links

Menu latéral de documentation

Le menu latéral de la barre de documentation est construit à partir de l'arborescence de la section courante commençant sous docs/.

Il affichera toutes les sections et leurs pages.

Si vous ne voulez pas lister une section ou une page, mettez l'option toc_hide à true dans l'entête :

toc_hide: true

Lorsque vous naviguez vers une section contenant du contenu, la section ou la page spécifique (par exemple _index.md) est affichée. Sinon, la première page à l'intérieur de cette section est affichée.

Navigateur de documentation

Le navigateur de page sur la page d'accueil de la documentation est construit en utilisant toutes les sections et pages qui sont directement sous la section docs.

Si vous ne voulez pas lister une section ou une page, mettez l'option toc_hide à true dans la partie avant :

toc_hide: true

Menu principal

Les liens du site dans le menu en haut à droite -- et aussi dans le pied de page -- sont construits par des recherches de pages. C'est pour s'assurer que la page existe réellement. Ainsi, si la section case-studies n'existe pas dans un site (langue), le lien n'apparaitra pas.

Paquets de pages

In addition to standalone content pages (Markdown files), Hugo supports Page Bundles.

One example is Custom Hugo Shortcodes. On considère qu'il s'agit d'un "paquet de feuilles". Tout ce qui se trouve sous le répertoire, y compris le fichier `index.md', fera partie du paquet. Cela inclut également les liens relatifs aux pages, les images qui peuvent être traitées, etc :

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Un autre exemple largement utilisé est celui du paquet includes. Il définit headless : true dans l'entête, ce qui signifie qu'il n'obtient pas son propre URL. Il n'est utilisé que dans d'autres pages.

en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Quelques notes importantes sur les fichiers dans les paquets :

• Pour les paquets traduits, tous les fichiers non contenus manquants seront hérités des fichiers de langue anglaise. Cela permet d'éviter les doublons.
• Tous les fichiers d'un bundle sont ce que Hugo appelle Resources et vous pouvez fournir des métadonnées par langue, comme les paramètres et le titre, même s'il ne prend pas en charge les entêtes (fichiers YAML etc.). Voir Page Resources Metadata.
• La valeur que vous obtenez de .RelPermalink d'un Resource est relative à la page. Voir Permalinks.

Styles

La source SASS des feuilles de style pour ce site est stockée sous src/sass et peut être construite avec make sass (notez que Hugo aura bientôt le support SASS, voir https://github.com/gohugoio/hugo/issues/4243.

A suivre

• Hugo shortcodes personnalisés
• Style guide

3.5 - Hugo Shortcodes personnalisés

Cette page explique les shortcodes Hugo personnalisés pouvant être utilisés dans la documentation de Kubernetes Markdown.

En savoir plus sur shortcodes dans la documentation Hugo.

Etat de la fonctionnalité

Dans une page de Markdown (fichier .md) de ce site, vous pouvez ajouter un code court pour afficher la version et l'état de la fonction documentée.

Feature state demo

Ci-dessous se trouve une démo de l'extrait d'état de la fonctionnalité, qui affiche la fonctionnalité comme stable dans Kubernetes version 1.10.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Rend à :

Les valeurs valides pour state sont :

• alpha
• beta
• deprecated
• stable

Feature state code

La version de Kubernetes affichée par défaut est celle de la page ou du site. Ceci peut être modifié en passant le paramètre for_k8s_version shortcode.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Rend à :

Alpha feature

{{< feature-state feature-state state="alpha" >}}

Rend à :

Beta feature

{{< feature-state feature-state state="beta" >}}

Rend à :

Stable feature

{{< feature-state feature-state state="stable" >}}

Rend à :

Deprecated feature

{{< feature-state feature-state state="deprecated" >}}

Rend à :

Glossaire

Vous pouvez faire référence à des termes du glossaire avec une inclusion qui met à jour et remplace automatiquement le contenu avec les liens pertinents de notre glossaire. When the term is moused-over by someone using the online documentation, the glossary entry displays a tooltip.

The raw data for glossary terms is stored at https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary, with a content file for each glossary term.

Démonstration du glossaire

Par exemple, le snippet suivant est rendu à cluster avec une infobulle :

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Tabs

Dans une page de démarque (fichier .md) de ce site, vous pouvez ajouter un jeu d'onglets pour afficher plusieurs saveurs d'une solution donnée.

The tabs shortcode takes these parameters:

• name: Le nom tel qu'il apparaît sur l'onglet.
• codelang: Si vous fournissez un contenu interne au shortcode tab, vous pouvez indiquer à Hugo quel langage de code utiliser pour activer la coloration syntaxique.
• include: Le fichier à inclure dans l'onglet. Si l'onglet vit dans un Hugo leaf bundle, le fichier -- qui peut être n'importe quel type MIME supporté par Hugo -- est recherché dans le bundle lui-même. Si ce n'est pas le cas, la page de contenu qui doit être incluse est recherchée par rapport à la page en cours. Notez qu'avec le include, vous n'avez pas de contenu interne de shortcode et devez utiliser la syntaxe de fermeture automatique. Par exemple, {{< tab name="Content File #1" include="example1" />}}. La langue doit être spécifiée sous codelang ou la langue est prise en compte en fonction du nom du fichier. Les fichiers non contenus sont mis en surbrillance par défaut.
• Si votre contenu interne est Markdown, vous devez utiliser le délimiteur % pour entourer l'onglet. Par exemple, {{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
• Vous pouvez combiner les variations mentionnées ci-dessus dans un ensemble d'onglets.

Ci-dessous se trouve une démo du raccourci des onglets.

Tabs demo: Code highlighting

{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}}
{{< /tabs >}}

Rend à:

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

Tabs demo: Inline Markdown and HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Rend à:

• Markdown
• HTML

Tabs demo: File include

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Rend à:

• Content File #1
• Content File #2
• JSON File

{
  "apiVersion": "v1",
  "kind": "PodTemplate",
  "metadata": {
    "name": "nginx"
  },
  "template": {
    "metadata": {
      "labels": {
        "name": "nginx"
      },
      "generateName": "nginx-"
    },
    "spec": {
        "containers": [{
          "name": "nginx",
          "image": "dockerfile/nginx",
          "ports": [{"containerPort": 80}]
        }]
    }
  }
}

A suivre

• En savoir plus sur Hugo.
• En savoir plus sur écrire un nouveau sujet.
• En savoir plus sur l'utilisation des page templates.
• En savoir plus sur staging your changes
• En savoir plus sur créer une pull request.

4 - Vue d'ensemble des documents de référence

Une grande partie de la documentation de référence de Kubernetes est générée à partir du code source de Kubernetes, à l'aide de scripts. Les rubriques de cette section expliquent comment générer ce type de contenu.

4.1 - 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:

• Git
• Golang version 1.9.1 ou ultérieur
• Docker
• etcd

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:

1. Générez une spécification OpenAPI à partir du code source de Kubernetes. Les outils pour cette étape sont kubernetes/kubernetes/hack.

2. 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.

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.

A suivre

• Génération de documents de référence pour les composants et les outils Kubernetes
• Génération de documentation de référence pour les commandes kubectl
• Génération de documentation de référence pour l'API de fédération Kubernetes

4.2 - Génération de la documentation de référence pour l'API de fédération Kubernetes

Cette page montre comment générer automatiquement des pages de référence pour l'API de fédération Kubernetes.

Pré-requis

• Vous devez avoir Git installé.

• Vous devez avoir Golang version 1.9.1 ou ultérieur installé, et votre variable d'environnement $GOPATH doit être définie.

• Vous devez avoir Docker installé.

• Vous devez savoir comment créer une pull request sur 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éation d'une pull request de documentation.

Exécution du script update-federation-api-docs.sh

Si vous ne possédez pas déjà le code source de la fédération Kubernetes, procurez-vous-le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/federation

Déterminez le répertoire de base de votre dépôt local kubernetes/federation. Par exemple, si vous avez suivi l'étape précédente pour obtenir le code source de la fédération, votre répertoire de base est $GOPATH/src/github.com/kubernetes/federation. Les étapes restantes se réfèrent à votre répertoire de base en tant que <fed-base>.

Exécutez le script de génération de documentation:

cd <fed-base>
hack/update-federation-api-reference-docs.sh

Le script exécute le k8s.gcr.io/gen-swagger-docs image pour générer cet ensemble de documents de référence:

• /docs/api-reference/extensions/v1beta1/operations.html
• /docs/api-reference/extensions/v1beta1/definitions.html
• /docs/api-reference/v1/operations.html
• /docs/api-reference/v1/definitions.html

Les fichiers générés ne sont pas publiés automatiquement. Ils doivent être copiés manuellement sur dépôt kubernetes/website.

Ces fichiers sont publiés à kubernetes.io/docs/reference:

• Federation API v1 Operations
• Federation API v1 Definitions
• Federation API extensions/v1beta1 Operations
• Federation API extensions/v1beta1 Definitions

A suivre

• Génération de documentation de référence pour l'API Kubernetes
• Génération de documentation de référence pour les commandes kubectl
• Génération de pages de référence pour les composants et les outils Kubernetes

4.3 - Génération de pages de référence pour les composants et les outils Kubernetes

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 et Federation.

Pré-requis

• Vous avez besoin d'une machine qui exécute Linux ou macOS.

• Ces logiciels doivent être installés:

  • Git

  • Golang version 1.13 ou ultérieure

  • make

  • gcc compiler/linker

• 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.

Obtenir deux dépôts

Si vous n'avez 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 clone du 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 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:

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

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.

PR 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.

Surveillez votre pull request cherry-pick jusqu'à ce qu'elle soit mergée dans la branche release.

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.
2. 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.
3. 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 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.

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:

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:

  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:

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:

...

    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.

A suivre

• Génération de documentation de référence pour les commandes kubectl
• Génération de documentation de référence pour l'API Kubernetes
• Génération de documentation de référence pour l'API de fédération Kubernetes

5 - Participez au SIG Docs

SIG Docs est l'un des groupes d'intérêts spéciaux au sein du projet Kubernetes, axé sur la rédaction, la mise à jour et la maintenance de la documentation de Kubernetes dans son ensemble. Pour plus d'informations sur le SIG consultez le dépôt GitHub de la communauté.

SIG Docs accueille le contenu et les critiques de tous les contributeurs. Tout le monde peut ouvrir une pull request (PR), et tout le monde est invité à déposer des questions sur le contenu ou à commenter les pull requests ouvertes.

Dans SIG Docs, vous pouvez aussi devenir un membre, relecteur, ou approbateur. Ces rôles nécessitent un plus grand accès et impliquent certaines responsabilités pour approuver et valider les changements. Voir appartenance à la communauté pour plus d'informations sur le fonctionnement de l'adhésion au sein de la communauté Kubernetes. Le reste de ce document décrit certaines fonctions uniques de ces rôles au sein du SIG Docs, responsable de la gestion de l’un des aspects les plus accessibles du public de Kubernetes: le site Web et la documentation de Kubernetes.

Rôles et responsabilités

Lorsqu'une pull request est mergée à la branche utilisée pour publier le contenu (actuellement master), ce contenu est publié et disponible dans le monde entier. Pour nous assurer que la qualité de notre contenu publié est élevée, nous limitons aux approbateurs SIG Docs le droit de merger des pull requests. Voici comment ce processus fonctionne.

• Lorsqu'une pull request a les deux labels lgtm et approve et n'a pas de label hold, la pull request est mergée automatiquement.
• Les membres de l'organisation Kubernetes et les approbateurs SIG Docs peuvent ajouter des commentaires à une pull request ou empêcher le merge automatique d'une pull request donnée (en ajoutant un commentaire /hold ou en retirant un commentaire /lgtm).
• Tout membre de Kubernetes peut ajouter le label lgtm, en ajoutant un commentaire /lgtm.
• Seul un approbateur membre de SIG Docs peut causer le merge d'une pull request en ajoutant un commentaire /approve. Certains approbateurs remplissent également des rôles spécifiques supplémentaires, tels que PR Wrangler or président(e) du SIG Docs.

Pour plus d'informations sur les attentes et les différences entre les rôles de membre de l'organisation Kubernetes et d'approbateurs SIG Docs, voir Types de contributeur. Les sections suivantes couvrent plus de détails sur ces rôles et leur fonctionnement dans SIG-Docs.

N'importe qui

Tout le monde peut ouvrir un ticket sur n'importe quelle partie de Kubernetes, y compris la documentation.

Toute personne ayant signé le CLA peut ouvrir une Pull Request. Si vous ne pouvez pas signer le CLA, le projet Kubernetes ne peut pas accepter votre contribution.

Membres

Tout membre de l'organisation Kubernetes peut faire une revue d'une pull request, et les membres de l’équipe SIG Docs demandent fréquemment aux membres d’autres SIG d'effectuer des révisions de documents pour des raisons de précision technique. SIG Docs accueille également des critiques et des commentaires indépendamment du statut de membre d'une personne dans l'organisation Kubernetes. Vous pouvez indiquer votre approbation en ajoutant un commentaire de /lgtm à une pull request. Si vous n'êtes pas membre de l'organisation Kubernetes, votre /lgtm n'a aucun effet sur les systèmes automatisés.

Tout membre de l’organisation Kubernetes peut ajouter un commentaire / hold pour empêcher la pull request d'être mergée. Tout membre peut également supprimer un commentaire /hold pour merger une PR s'il a déjà les deux commentaires /lgtm et /approve appliqué par les personnes appropriées.

Devenir membre

Après avoir soumis avec succès au moins 5 pull requests significatives, vous pouvez demander l'adhésion dans l'organisation Kubernetes. Suivez ces étapes:

1. Trouvez deux relecteurs ou approbateurs pour parrainer votre adhésion.

   Demander un parrainage dans le canal #sig-docs sur l'instance de Kubernetes Slack ou sur la mailing list SIG Docs.

   Note: N'envoyez pas de courrier électronique direct ou de message direct Slack à un membre individuel de SIG Docs.

2. Ouvrez un ticket Github dans le dépôt kubernetes/org pour adhérer à l'organisation. Remplissez le modèle en suivant les directives de l'Adhésion à la communauté.

3. Informez vos sponsors du ticket Github, soit en les mentionnant dans le ticket Github (en ajoutant un commentaire avec @<Github-username>) ou en leur envoyant directement le lien, afin qu’ils puissent ajouter un vote + 1.

4. Lorsque votre adhésion est approuvée, le membre de l'équipe d'administration github affecté à votre demande met à jour le ticket Github pour indiquer son approbation, puis ferme le ticket Github. Félicitations, vous êtes maintenant membre!

Si, pour une raison quelconque, votre demande d'adhésion n'est pas acceptée immédiatement, le comité des membres fournit des informations ou des mesures à prendre avant de présenter une nouvelle demande.

Relecteurs

Les relecteurs sont membres du groupe Github @kubernetes/sig-docs-pr-reviews. Voir Equipes et groupes au sein de SIG Docs.

Les relecteurs examinent les Pull Request de documentation et font des commentaires sur les changements proposés.

L'automatisation assigne des relecteurs aux pull requests, et les contributeurs peuvent demander une revue d'un relecteur spécifique en laissant un commentaire tel que: /assign [@_github_handle]. Pour indiquer qu'une pull request est techniquement exacte et ne nécessite aucune modification supplémentaire, un examinateur ajoute un commentaire /lgtm à la Pull Request.

Si le relecteur affecté n'a pas encore revu le contenu, un autre relecteur peut intervenir. En outre, vous pouvez affecter des relecteurs techniques et attendre qu'ils fournissent des /lgtm.

Pour un changement trivial ou ne nécessitant aucun examen technique, l'approbateur SIG Docs peut fournir le /lgtm aussi.

Un commentaire /approve d'un relecteur est ignoré par l'automatisation.

Pour en savoir plus sur comment devenir un relecteur SIG Docs et sur les responsabilités et l’engagement de temps que cela implique, voir Devenir relecteur ou approbateur.

Devenir relecteur

Lorsque vous remplissez les conditions requises, vous pouvez devenir un relecteur SIG Docs. Les relecteurs d'autres SIG doivent demander séparément le statut de relecteur dans le SIG Docs.

Pour postuler, ouvrez une pull request et ajoutez vous à la section reviewers du fichier top-level OWNERS dans le dépôt kubernetes/website. Affectez la PR à un ou plusieurs approbateurs SIG Docs.

Si votre pull request est approuvée, vous êtes maintenant un relecteur SIG Docs. K8s-ci-robot vous assignera et vous suggérera en tant que relecteur pour les nouvelles Pull Requests.

Si vous êtes approuvé, demandez qu’un approbateur SIG Docs en cours vous ajoute au groupe Github @kubernetes/sig-docs-pr-reviews. Seuls les membres du groupe Github kubernetes-website-admins peuvent ajouter de nouveaux membres à un groupe Github.

Approbateurs

Les approbateurs sont membres du groupe Github @kubernetes/sig-docs-maintainers. Voir Equipes et groupes au sein de SIG Docs.

Les approbateurs ont la capacité de merger une PR, et ainsi, publier du contenu sur le site Web de Kubernetes. Pour approuver une PR, un approbateur laisse un commentaire /approve sur la PR. Si quelqu'un qui n'est pas un approbateur laisse le commentaire d'approbation, l'automatisation l'ignore.

Si la PR a déjà un /lgtm, ou si l'approbateur fait également des commentaires avec /lgtm, la PR est mergée automatiquement. Un approbateur SIG Docs ne doit laisser qu'un /lgtm sur un changement qui ne nécessite pas de relecture supplémentaire.

Pour en savoir plus sur comment devenir un approbateur SIG Docs et sur les responsabilités et l’engagement de temps que cela implique, voir Devenir relecteur ou approbateur.

Devenir approbateur

Lorsque vous remplissez les conditions requises, vous pouvez devenir un approbateur SIG Docs. Les approbateurs appartenant à d'autres SIG doivent demander séparément le statut d'approbateur dans SIG Docs.

Pour postuler, ouvrez une pull request pour vous ajouter à la section approvers du fichier top-level OWNERS dans le dépot kubernetes/website. Affectez la PR à un ou plusieurs approbateurs SIG Docs.

Si votre Pull Request est approuvée, vous êtes à présent approbateur SIG Docs. Le K8s-ci-robot vous assignera et vous suggérera en tant que relecteur pour les nouvelles Pull Requests.

Si vous êtes approuvé, demandez qu’un approbateur SIG Docs en cours vous ajoute au groupe Github @kubernetes/sig-docs-maintainers. Seuls les membres du groupe Github kubernetes-website-admins peuvent ajouter de nouveaux membres à un groupe Github.

Devenir un administrateur de site Web

Les membres du groupe GitHub kubernetes-website-admins peuvent gérer l’appartenance au groupe Github et disposer de tous les droits administratifs sur les paramètres du dépôt, y compris la possibilité d'ajouter, de supprimer et de debugger des Webhooks. Tous les approbateurs SIG Docs n'ont pas besoin de ce niveau d'accès.

Si vous pensez avoir besoin de ce niveau d’accès, adressez-vous à un administrateur de site Web existant ou posez la question dans le canal Slack #sig-docs.

Auxiliaires de traitement des Pull Requests

Les approbateurs SIG Docs sont ajoutés au calendrier de rotations des auxiliaires de traitement des PullRequests pour les rotations hebdomadaires. Tous les approbateurs SIG Docs devraient participer à cette rotation. Voir Soyez l'auxiliaire des PR pendant une semaine pour plus de détails.

Présidence du SIG Docs

Chaque SIG, y compris SIG Docs, sélectionne un ou plusieurs membres du SIG qui assumeront les fonctions de président(e). Ce sont des points de contact entre SIG Docs et d’autres parties de l’organisation Kubernetes. Ils nécessitent une connaissance approfondie de la structure du projet Kubernetes dans son ensemble et du fonctionnement de SIG Docs au sein de celui-ci. Voir Direction pour la liste actuelle des président(e)s.

Equipes SIG Docs et automatisation

L'automatisation dans SIG Docs repose sur deux mécanismes différents: Groupes Github et fichiers OWNERS.

Groupes Github

Le groupe SIG Docs définit deux équipes sur Github:

• @kubernetes/sig-docs-maintainers
• @kubernetes/sig-docs-pr-reviews

Chacun peut être référencé avec son @name dans Github, commentez pour communiquer avec tous les membres de ce groupe.

Ces équipes peuvent avoir des membres en commun. Pour l'affectation des tickets, des pull requests, et aider la validation des PR, l'automatisation utilise les informations des fichiers OWNERS.

OWNERS files et front-matter

Le projet Kubernetes utilise un outil d'automatisation appelé prow pour l'automatisation liée aux Github issues et aux pull requests. Le dépôt du site web Kubernetes utilise deux plugins prow:

• blunderbuss
• approve

Ces deux plugins utilisent les fichiers OWNERS et OWNERS_ALIASES à la racine du dépôt Github kubernetes/website pour contrôler comment prow fonctionne.

Un fichier OWNERS contient une liste de personnes qui sont des relecteurs et des approbateurs SIG Docs. Les fichiers OWNERS existent aussi dans les sous-dossiers, et peuvent ignorer qui peut agir en tant que relecteur ou approbateur des fichiers de ce sous-répertoire et de ses descendants. Pour plus d'informations sur les fichiers OWNERS en général, voir OWNERS.

En outre, un fichier Markdown individuel peut répertorier les relecteurs et les approbateurs dans l'entête, soit en répertoriant les noms d’utilisateur ou les groupes de Github.

La combinaison des fichiers OWNERS et des entêtes dans les fichiers Markdown déterminent les suggestions automatiques de relecteurs dans la PullRequest.

A suivre

Pour plus d'informations sur la contribution à la documentation Kubernetes, voir:

• Commencez à contribuer
• Documentation style

6 - Traduction de la documentation Kubernetes

La documentation de Kubernetes est disponible dans plusieurs langues. Nous vous encourageons à ajouter de nouvelles traductions!

Commencer

Les traductions doivent avoir certains pré-requis pour le workflow (comment traduire) et la sortie (quoi traduire) avant de publier.

Pour ajouter une nouvelle localisation de la documentation de Kubernetes, vous devrez mettre à jour le site web en modifiant le paramètre site configuration et directory structure. Alors vous pouvez commencer la traduction de documents!

Indiquez à Kubernetes SIG Docs que vous souhaitez créer une traduction! Rejoignez le canal Slack SIG Docs. Nous sommes heureux de vous aider à démarrer et à répondre à toutes vos questions.

Toutes les équipes de traduction doivent être autonomes avec leurs propres ressources. Nous sommes heureux d'accueillir votre travail, mais nous ne pouvons pas le traduire pour vous.

Fork et cloner le dépôt

D'abord, créez votre fork du dépôt kubernetes/website.

Ensuite, clonez ce dépôt et mettez vous dedans (avec une commande cd):

git clone https://github.com/kubernetes/website
cd website

Trouvez votre code de langue à deux lettres

Consultez la norme ISO 639-1 pour le code de pays en deux lettres de votre localisation. Par exemple, le code à deux lettres pour l'allemand est de.

Modifier la configuration du site

Le site web de Kubernetes utilise Hugo comme son web framework. La configuration Hugo du site Web se trouve dans le fichier config.toml. Pour prendre en charge une nouvelle localisation, vous devrez modifier config.toml.

Ajoutez un bloc de configuration pour la nouvelle langue dans config.toml, sous le bloc [languages] existant. Le bloc allemand, par exemple, ressemble à :

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3

Lors de l'attribution d'un paramètre de weight à votre bloc, trouvez le bloc de langue ayant le weight le plus élevé et ajoutez 1 à cette valeur.

Pour plus d'informations sur le support multilingue de Hugo, voir "Multilingual Mode".

Ajouter un nouveau répertoire de localisation

Ajoutez un sous-répertoire spécifique à la langue dans le répertoire content du dépôt. Par exemple, le code à deux lettres pour l'allemand est "de" :

mkdir content/de

Ajouter un README localisé

Pour guider les autres contributeurs à la localisation, ajoutez un nouveau README-**.md au plus haut niveau de k/website, où ** est le code de langue à deux lettres. Par exemple, un fichier README allemand serait README-de.md.

Fournir des conseils aux contributeurs à la localisation dans le fichier localisé README-**.md. Incluez les mêmes informations que celles contenues dans README.mdainsi que :

• Un point de contact pour le projet de localisation
• Toute information spécifique à la localisation

Après avoir créé le fichier README localisé, ajoutez un lien vers le fichier à partir du fichier anglais principal, [README.md's Localizing Kubernetes Documentation] et incluez les coordonnées des personnes-ressources en anglais. Vous pouvez fournir un identifiant GitHub, une adresse e-mail, Slack channel, ou toute autre méthode de contact.

Translating documents

Localiser toute la documentation de Kubernetes est une tâche énorme. Il n'y a pas de mal à commencer petit et progresser avec le temps.

Au minimum, toutes les localisations doivent inclure :

Les documents traduits doivent résider dans leur propre sous-répertoire content/**/, mais sinon suivre le même chemin URL que la source anglaise. Par exemple, pour préparer le tutoriel Kubernetes Basics à traduire en allemand, créez un sous-dossier sous le dossier `content/de/' et copiez la source anglaise :

mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md

Pour un exemple de demande liée à la localisation pull request, this pull request au Kubernetes website repo a ajouté la localisation coréenne aux documents Kubernetes.

Fichiers sources

Les localisations doivent utiliser les fichiers anglais de la version la plus récente comme source. La version la plus récente est v1.23.

Pour trouver les fichiers sources de la version la plus récente :

1. Accédez au dépôt du site web de Kubernetes à l'adresse suivante https://github.com/kubernetes/website.
2. Sélectionnez la branche `release-1.X' pour la version la plus récente.

La dernière version est v1.23, donc la branche de la release la plus récente est release-1.23.

Chaînes de sites en i18n/

Les localisations doivent inclure le contenu des éléments suivants i18n/en.toml dans un nouveau fichier spécifique à la langue. Prenons l'allemand comme exemple : i18n/de.toml.

Ajouter un nouveau fichier de localisation dans i18n/. Par exemple, avec l'allemand (de) :

cp i18n/en.toml i18n/de.toml

Traduisez ensuite la valeur de chaque chaîne de caractères :

[docs_label_i_am]
other = "ICH BIN..."

La localisation des chaînes de caractères du site vous permet de personnaliser le texte et les fonctionnalités du site : par exemple, le texte du copyright légal dans le pied de page de chaque page.

Logistique de projet

Contactez les responsables du SIG Docs

Contactez l'un des présidents du Kubernetes SIG Docs lorsque vous démarrez une nouvelle localisation.

Mainteneurs

Chaque traduction doit fournir ses propres responsables. Les responsables peuvent appartenir à une ou plusieurs organisations. Dans la mesure du possible, les pull requests de traduction doivent être approuvées par un relecteur d'une organisation différente de celle du traducteur.

Une traduction doit avoir un minimum de deux mainteneurs. (Il n'est pas possible de relire et d'approuver son propre travail.)

Gestion des branches

Étant donné que les projets de traduction sont des efforts hautement collaboratifs, nous encourageons les équipes à travailler à partir d’une branche de développement partagée.

Pour collaborer sur une branche de développement:

1. A team member opens a development branch, usually by opening a new pull request against a source branch on https://github.com/kubernetes/website.

   Nous recommandons le schéma de nommage de branche suivant :

   dev-<source version>-<language code>.<team milestone>

   Par exemple, un approbateur d'une équipe de localisation allemande ouvre la branche développement dev-1.12-de.1 directement contre le dépôt k/website, basé sur la branche source pour Kubernetes v1.12.

2. Les contributeurs individuels ouvrent des branches de fonctionnalités basées sur la branche de développement.

   Par exemple, un contributeur allemand ouvre une pull request avec les modifications suivantes kubernetes:dev-1.12-de.1 sur username:local-branch-name.

3. Les approbateurs examinent et mergent les branches de fonctionnalités dans la branche de développement.

4. Périodiquement, un approbateur fusionne la branche de développement à sa branche source.

Répétez les étapes 1 à 4 au besoin jusqu'à ce que la localisation soit terminée. Par exemple, les branches de développement allemandes suivantes le seraient : dev-1.12-de.2, dev-1.12-de.3, etc.

Les équipes doivent fusionner le contenu localisé dans la même branche de publication d'où provient le contenu. Par exemple, une direction du développement provenant de release-1.23 doit se fonder sur release-1.23.

Un approbateur doit maintenir une branche de développement en la tenant à jour avec sa branche source et en résolvant les conflits entre les branches. Plus une branche de développement reste ouverte longtemps, plus elle nécessite généralement de maintenance. Envisagez de merger périodiquement les branches de développement et d’en ouvrir de nouvelles, plutôt que de conserver une branche de développement extrêmement ancienne.

Seuls les approbateurs peuvent accepter les pull requests, mais n'importe qui peut en ouvrir une avec une nouvelle branche de développement. Aucune autorisation spéciale n'est requise.

Pour plus d'informations sur le travail à partir de forks ou directement à partir du dépôt, voir "fork and clone the repo".

Upstream contributions

SIG Docs souhaite la bienvenue aux contributions et corrections upstream à la source anglaise.

A suivre

Une fois qu'une traduction répond aux exigences de logistique et à une couverture admissible, le SIG docs se chargera des taches suivantes:

• Activer la sélection de la langue sur le site Web
• Publier la disponibilité de la traduction via les canaux de la Cloud Native Computing Foundation, y compris sur le blog de Kubernetes.