Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Contribuez à ce guide
Tout le monde peut contribuer au guide des meilleures pratiques. Le guide des meilleures pratiques d'EKS est rédigé dans le AsciiDoc format suivant GitHub.
Résumé pour les contributeurs existants
-
Ouvrez le
bpg-docs.code-workspaceavec VS Code pour installer automatiquement l' AsciiDoc extension. -
Pour en savoir plus sur l'AsciiDoc extension
, rendez-vous sur Visual Studio Marketplace.
-
-
Les fichiers source du site Web AWS Docs sont stockés dans
latest/bpg -
La syntaxe est très similaire à celle de Markdown.
-
Consultez la référence de syntaxe
dans les AsciiDoctor documents.
-
-
La plateforme Docs se déploie
latest/bpg/imagesuniquement. Chacune des sections du guide comporte un lien symbolique renvoyant vers ce répertoire. Par exemple,latest/bpg/networking/imagespointe verslatest/bpg/images.
Configuration d'un environnement d'édition local
Si vous prévoyez de modifier fréquemment le guide, configurez un environnement d'édition local.
Forker et cloner le dépôt
Vous devez être familiarisé avec gitgithub, et les éditeurs de texte. Pour plus d'informations sur la prise en main de git etgithub, consultez la section Prise en main de votre GitHub compte
-
Consultez le guide des meilleures pratiques d'EKS sur GitHub
. -
Créez un fork du dépôt du projet. Découvrez comment créer un dépôt
dans la GitHub documentation. -
Clonez votre fork du dépôt du projet. Découvrez comment cloner votre dépôt bifurqué.
Ouvrez l'espace de travail VS Code
AWS recommande d'utiliser le code Visual Studio de Microsoft pour modifier le guide. Pour plus d'informations sur VS Code, voir Télécharger Visual Studio Code
-
Ouvrez VS Code.
-
Ouvrez le
bpg-docs.code-workspacefichier depuis le dépôt cloné. -
Si c'est la première fois que vous ouvrez cet espace de travail, acceptez l'invite d'installation de l' AsciiDoc extension. Cette extension vérifie la syntaxe des AsciiDoc fichiers et génère un aperçu en direct.
-
Accédez au
latest/bpgrépertoire. Ce répertoire contient les fichiers source déployés sur le site de documentation AWS. Les fichiers sources sont organisés par section du guide, telle que « sécurité » ou « réseau ».
Modifier un fichier
-
Ouvrez un fichier dans l'éditeur.
-
Consultez la AsciiDoc syntaxe pour savoir comment créer des en-têtes, des liens et des listes.
-
Vous pouvez utiliser la syntaxe Markdown pour mettre en forme du texte, créer des listes et des en-têtes. Vous ne pouvez pas utiliser la syntaxe Markdown pour créer des liens.
-
-
Ouvrez un aperçu en direct de la page.
-
Appuyez d'abord sur
ctrl-koucmd-k(selon le clavier). Ensuite, appuyez surv. Cela ouvre un aperçu en mode partagé.
-
AWS suggère d'utiliser des branches de fonctionnalités pour organiser vos modifications. Apprenez à créer des branches avec git.
Soumettre une pull request
Vous pouvez créer une pull request depuis le GitHub site Web ou le GitHub cli.
Découvrez comment créer une pull request à partir d'un fork
Apprenez à créer une pull request
Utilisez l'éditeur Web github.dev
L'éditeur github.dev Web est basé sur VS Code. C'est un excellent moyen de modifier plusieurs fichiers et de prévisualiser le contenu sans aucune configuration.
Il prend en charge l' AsciiDoc extension. Vous pouvez effectuer des opérations git à l'aide de l'interface graphique. L'éditeur Web ne possède pas de shell ou de terminal pour exécuter des commandes.
Vous devez avoir un GitHub compte. Vous serez invité à vous connecter si nécessaire.
🚀 Lancez l'éditeur GitHub Web.
Modifier une seule page
Vous pouvez rapidement mettre à jour des pages individuelles en utilisant GitHub. Chaque page contient un lien « 📝 Modifier cette page sur GitHub » en bas de page.
-
Accédez à la page de ce guide que vous souhaitez modifier
-
Cliquez sur le lien « Modifier cette page sur GitHub » en bas
-
Cliquez sur l'icône en forme de crayon d'édition en haut à droite de l'afficheur de GitHub fichiers, ou appuyez sur
e -
Modifier le fichier
-
Soumettez vos modifications à l'aide du bouton « Valider les modifications... ». Ce bouton crée une GitHub pull request. Les responsables du guide examineront cette pull request. Un réviseur approuvera la pull request ou demandera des modifications.
Afficher et définir l'ID d'une page
Cette page explique comment afficher et définir l'ID de page.
L'ID de page est une chaîne unique qui identifie chaque page du site de documentation. Vous pouvez consulter l'identifiant de page dans la barre d'adresse de votre navigateur lorsque vous vous trouvez sur une page spécifique. L'ID de page est utilisé pour l'URL, le nom du fichier et pour créer des liens de référence croisée.
Par exemple, si vous consultez cette page, l'URL dans la barre d'adresse de votre navigateur ressemblera à ce qui suit :
https://docs.aws.amazon.com/view-set-page-id.html
La dernière partie de l'URL (view-set-page-id) est l'ID de page.
Définissez l'ID de page
Lorsque vous créez une nouvelle page, vous devez définir l'ID de page dans le fichier source. L'ID de page doit être une chaîne concise avec un trait d'union décrivant le contenu de la page.
-
Ouvrez le fichier source de votre nouvelle page dans un éditeur de texte.
-
En haut du fichier, ajoutez la ligne suivante. Il doit se trouver au-dessus du premier titre.
[#my-new-page]Remplacez
my-new-pagepar l'ID de page de votre nouvelle page. -
Enregistrez le fichier.
Note
La page IDs doit être unique sur l'ensemble du site de documentation. Si vous essayez d'utiliser un identifiant de page existant, une erreur de compilation s'affichera.
Création d'une nouvelle page
Découvrez comment créer une nouvelle page et mettre à jour la table des matières du guide.
Création de métadonnées de page
-
Déterminez le titre de la page et le titre abrégé de la page. Le titre abrégé de la page est facultatif, mais recommandé si le titre de la page comporte plus de quelques mots.
-
Déterminez l'ID de la page. Cela doit être unique dans le guide des meilleures pratiques d'EKS. La convention consiste à utiliser toutes les minuscules et à séparer les mots par.
- -
Créez un nouveau fichier asciidoc, dans un dossier si nécessaire, et ajoutez-y le texte suivant :
[. » sujet "] [#<page-id>] = <page-title>:info_titleabbrev : < > page-short-title
Par exemple,
[. » topic "] [#scalability] = Meilleures pratiques d'évolutivité d'EKS : info_titleabbrev : Scalabilité
Ajouter à la table des matières
-
Ouvrez le fichier de la page parent dans la table des matières. Pour les nouvelles sections du guide de haut niveau, le fichier parent est
book.adoc. -
Au bas du fichier parent, mettez à jour et insérez la directive suivante :
inclure : <new-filename>[leveloffset=+1]
Par exemple,
include : :dataplane.adoc [leveloffset=+1]
Insérer une image
-
Trouvez le préfixe d'image de la page que vous êtes en train de modifier. Vérifiez la
:imagesdir:propriété dans l'en-tête du fichier. À titre d'exemple,`:imagesdir: images/reliability/ -
Placez votre image dans ce chemin, tel que
latest/bpg/images/reliability -
Déterminez le texte alternatif approprié pour votre image. Rédigez une brève description détaillée de l'image. Par exemple, « schéma d'un VPC avec trois zones de disponibilité » est un texte alternatif approprié.
-
Mettez à jour l'exemple suivant avec le texte alternatif et le nom de fichier de l'image. Insérez à l'endroit souhaité.
image : <image-filename>[< image-alt-text >]
Par exemple,
image : : eks-data-plane-connectivity .jpeg [Schéma de réseau]
Vérifiez le style avec Vale
-
Exécutez
vale sync -
Installez l'extension Vale
depuis Visual Studio Marketplace. -
Redémarrez VS Code et ouvrez un AsciiDoc fichier
-
VS Code souligne le texte problématique. Apprenez à gérer les erreurs et les avertissements
dans la documentation de VS Code.
Création d'un aperçu local
-
Installez l'
asciidoctoroutil sousbrewLinux ou macOS-
Découvrez comment installer asciidoctor cli
dans la documentation. AsciiDoctor -
Découvrez comment installer le gestionnaire de paquets Brew
.
-
-
Ouvrez un terminal, puis naviguez vers
latest/bpg/ -
Exécutez
asciidoctor book.adoc-
Passez en revue les avertissements et les erreurs de syntaxe
-
-
Ouvrez le fichier
book.htmlde sortie.-
Sur macOS, vous pouvez
open book.htmlexécuter l'aperçu dans votre navigateur par défaut pour ouvrir l'aperçu.
-
AsciiDoc Aide-mémoire
Formatage de base
*bold text*
_italic text_
`monospace text`En-têtes
= Document Title (Header 1)
== Header 2
=== Header 3
==== Header 4
===== Header 5
====== Header 6Listes
Listes non ordonnées :
- Item 1
- Item 2
-- Subitem 2.1
-- Subitem 2.2
- Item 3Listes ordonnées :
. First item
. Second item
.. Subitem 2.1
.. Subitem 2.2
. Third itemLiens
External link: https://example.com[Link text]
Internal link: <<page-id>>
Internal link: xref:page-id[Link text]Images
image::image-file.jpg[Alt text]
Blocs de code
[source,python]
----
def hello_world():
print("Hello, World!")
----Tables
Apprenez à créer une table de base.
[cols="1,1"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 1, row 3
|Cell in column 2, row 3
|===Des admonestations
NOTE: This is a note admonition.
WARNING: This is a warning admonition.
TIP: This is a tip admonition.
IMPORTANT: This is an important admonition.
CAUTION: This is a caution admonition.Aperçu :
Note
Il s'agit d'une mise en garde.
Inclut
include::filename.adoc[]