Partager via

Contribuer à l’aide de GitHub Codespaces

GitHub dispose d’une fonctionnalité appelée Codespaces que vous pouvez utiliser pour contribuer à la documentation PowerShell sans avoir à installer ou configurer un logiciel localement. Lorsque vous utilisez un espace de code, vous obtenez les mêmes outils de création que l’équipe utilise pour écrire et modifier.

Vous pouvez utiliser un espace de code dans votre navigateur, en apportant vos contributions dans VS Code hébergé sur Internet. Si VS Code est installé localement, vous pouvez également vous connecter à l’espace de code.

Outils disponibles

Lorsque vous utilisez un espace de code pour contribuer à la documentation PowerShell, votre éditeur dispose déjà de ces outils :

  • Markdownlint pour vérifier votre syntaxe Markdown.
  • cSpell pour vérifier votre orthographe.
  • Vale pour vérifier votre prose.
  • Le Pack Learn Authoring pour l’insertion d’une syntaxe spécifique à la plateforme, la prévisualisation de votre contribution et bien plus encore.
  • L'extension Reflow Markdown permet de reformater votre Markdown selon vos besoins, ce qui facilite la lecture et la modification.
  • Extension formateur de tableau pour rendre vos tables plus lisibles sans avoir à aligner manuellement les colonnes.
  • Extension change-case pour convertir la casse de vos titres et de votre prose.
  • Extension GitLens pour examiner les modifications de fichier historiques.
  • Extension PowerShell pour interagir avec la création d’exemples PowerShell.
  • Le tracker Gremlins de Visual Studio Code permettant de détecter les caractères problématiques dans votre Markdown.

Coûts

GitHub Codespaces peut être utilisé gratuitement jusqu’à 120 heures de base par mois. L’utilisation mensuelle est calculée sur tous vos référentiels, pas seulement dans la documentation.

Pour plus d’informations sur la tarification, consultez À propos de la facturation pour GitHub Codespaces.

Conseil / Astuce

Si vous êtes à l’aise avec les conteneurs et Docker, vous pouvez obtenir la même expérience en utilisant le devcontainer défini pour les référentiels de documentation PowerShell. Il n’existe aucun coût associé à l’utilisation de devcontainers. Pour plus d’informations, consultez le didacticiel Conteneurs de développement.

Création de votre espace de code GitHub

Pour créer votre Espace de code GitHub pour contribuer à la documentation PowerShell, procédez comme suit :

  1. Ouvrez https://github.com/codespaces dans votre navigateur.
  2. Sélectionnez le bouton « Nouvel espace de code » en haut à droite de la page.
  3. Dans la page « Créer un espace de codes », sélectionnez le bouton « Sélectionner un référentiel » et tapez le nom du référentiel auquel vous souhaitez contribuer, par exemple MicrosoftDocs/PowerShell-Docs.
  4. Laissez tous les autres paramètres comme valeur par défaut.
  5. Sélectionnez le bouton « Créer un espace de code ».

Après avoir suivi ces étapes, GitHub crée un espace de code pour ce référentiel et le configure pour vous. Lorsque l’espace de code est prêt, la page actualise et affiche l’interface utilisateur de l’éditeur web pour l’espace de code. L’interface utilisateur est basée sur VS Code et fonctionne de la même façon.

Ouverture de votre espace de code GitHub

Pour ouvrir votre Espace de code GitHub dans le navigateur, procédez comme suit :

  1. Ouvrez https://github.com/codespaces dans votre navigateur.
  2. La page répertorie vos espaces de code. Recherchez l’espace de code créé pour le référentiel auquel vous souhaitez contribuer et sélectionnez-le.

Une fois que vous avez sélectionné votre espace de code, GitHub l’ouvre dans la même fenêtre. À partir de là, vous êtes prêt à contribuer.

Pour ouvrir votre GitHub Codespace dans VS Code, suivez les étapes de l’utilisation de GitHub Codespaces dans Visual Studio Code.

Rédaction dans vos espaces de code GitHub

Une fois que votre GitHub Codespace est ouvert dans votre navigateur ou VS Code, la contribution à la documentation suit le même processus.

Le reste de cet article décrit une sélection de tâches que vous pouvez effectuer dans votre espace de code GitHub lors de l’écriture ou de la modification de votre contribution.

Lorsque vous souhaitez transformer un lien inline, par [some text](destination.md)exemple, en lien de référence, [some text][01]sélectionnez la destination du lien dans l’éditeur. Vous pouvez ensuite :

  1. Cliquez avec le bouton droit sur la destination du lien, puis sélectionnez « Refactoriser... » dans le menu contextuel.
  2. Appuyez sur Ctrl+Maj+R.

L’une ou l’autre action déclenche le menu contextuel de refactorisation. Pour remplacer le (destination.md) par [def] dans le lien, sélectionnez Extraire vers la définition du lien dans le menu contextuel. Vous pouvez renommer la définition en tapant un nom.

Pour la documentation PowerShell, nous utilisons des définitions de liens de référence numériques à deux chiffres, comme [01] ou [31]. Utilisez uniquement les définitions de liens de référence dans les articles et la documentation conceptuelle. N’utilisez pas les définitions de liens de référence dans la documentation de référence de l’applet de commande.

Corriger les violations du style de la prose

Lorsque vous passez en revue un article dans votre espace de code, Vale vérifie automatiquement l’article lorsque vous l’ouvrez pour la première fois et chaque fois que vous l’enregistrez. Si Vale trouve des infractions aux règles de style, il les met en surbrillance dans le document avec des soulignements ondulés colorés.

Pointez sur une violation pour afficher plus d’informations sur celui-ci.

Pour ouvrir une page web qui explique la règle, sélectionnez le nom de la règle dans les informations de pointage. Pour ouvrir la règle et passer en revue son implémentation, sélectionnez le nom de fichier de la règle (se terminant par .yml).

Si la règle prend en charge un correctif rapide, vous pouvez sélectionner « Correctif rapide ... » dans les informations de pointage pour la violation et appliquez l’un des correctifs suggérés en le sélectionnant dans le menu contextuel. Vous pouvez également appuyer sur Ctrl+. Lorsque votre curseur se trouve sur un problème mis en surbrillance pour appliquer un correctif rapide si la règle la prend en charge.

Si la règle ne prend pas en charge les correctifs rapides, lisez le message de la règle et corrigez-la si vous le pouvez. Si vous ne savez pas comment le corriger, les éditeurs peuvent faire une suggestion lors de l’examen de votre demande de tirage.

Résoudre les problèmes de syntaxe

Lorsque vous passez en revue un article dans votre espace de code, Markdownlint vérifie automatiquement l’article lorsque vous l’ouvrez et que vous tapez. Si Markdownlint trouve des problèmes de syntaxe, il les met en surbrillance dans le document avec des soulignements ondulés colorés.

Pointez sur une violation pour afficher plus d’informations sur celui-ci. Pour ouvrir une page web qui explique la règle, sélectionnez l’ID de la règle dans les informations de pointage.

Si la règle prend en charge un correctif rapide, vous pouvez sélectionner « Correctif rapide ... » dans les informations de pointage pour la violation et appliquez l’un des correctifs suggérés en le sélectionnant dans le menu contextuel. Vous pouvez également appuyer sur Ctrl+. Lorsque votre curseur se trouve sur un problème mis en surbrillance pour appliquer un correctif rapide si la règle la prend en charge.

Si la règle ne prend pas en charge les correctifs rapides, lisez le message de la règle et corrigez-la si vous le pouvez. Si vous ne savez pas comment le corriger, les éditeurs peuvent faire une suggestion lors de l’examen de votre demande de tirage.

Vous pouvez également appliquer des correctifs à toutes les violations de syntaxe dans un article. Pour ce faire, ouvrez la palette de commandes et tapez Fix all supported markdownlint violations in the document. Lorsque vous tapez, la palette de commandes filtre les commandes disponibles. Sélectionnez la commande « Corriger toutes les violations markdownlint prises en charge dans le document ». Quand vous le faites, Markdownlint met à jour le document pour résoudre les violations pour lesquelles il a un correctif rapide.

Mettre en forme un tableau

Pour mettre en forme une table Markdown, placez votre curseur dans ou sur le tableau de votre Markdown. Ouvrez la palette de commandes et recherchez la Table: Format Current commande. Lorsque vous sélectionnez cette commande, elle met à jour le Markdown pour aligner et espacer votre table afin d'améliorer la lisibilité.

Elle convertit une table définie comme suit :

| foo | bar | baz |
|:--:|:--|-:|
| a | b | c |

Dans ce cas :

|  foo  | bar  | baz  |
| :---: | :--- | ---: |
|   a   | b    |    c |

Insérer une alerte

La documentation utilise des alertes pour rendre les informations plus notables pour un lecteur.

Pour insérer une alerte, vous pouvez ouvrir la palette de commandes et rechercher la Learn: Alert commande. Lorsque vous sélectionnez cette commande, elle ouvre un menu contextuel. Sélectionnez le type d’alerte que vous souhaitez ajouter. Lorsque vous le faites, la commande insère le Markdown de l'alerte à votre curseur dans le document.

Faire en sorte qu’un titre utilise la casse de phrase

Pour convertir la casse d’un titre, mettez en surbrillance le texte du titre à l’exception des symboles de début # , qui définissent le niveau de titre. Lorsque le texte est mis en surbrillance, ouvrez la palette de commandes et recherchez la Change case sentence commande. Lorsque vous sélectionnez cette commande, elle modifie la casse du texte mis en surbrillance.

Vous pouvez également utiliser les commandes de majuscules/minuscules pour n’importe quel texte du document.

Ouvrir la palette de commandes

Vous pouvez utiliser la palette de commandes de VS Code pour exécuter de nombreuses commandes utiles.

Pour ouvrir la palette de commandes dans l’interface utilisateur, sélectionnez « Affichage » dans la barre de menus supérieure. Sélectionnez ensuite « Palette de commandes... » dans le menu contextuel.

Pour ouvrir la palette de commandes avec votre clavier, appuyez sur la combinaison de touches de votre système d’exploitation :

  • Windows et Linux : Ctrl+Maj+P
  • macOS : Cmd+Shift+P

Afficher un aperçu de votre contribution

Pour afficher un aperçu de votre contribution, ouvrez la palette de commandes et recherchez la Markdown: Open Preview commande. Lorsque vous sélectionnez cette commande, VS Code ouvre un aperçu du document actif. Le style de l’aperçu correspond à la plateforme Learn.

Remarque

Les liens relatifs au site et aux références croisées ne fonctionnent pas dans l'aperçu.

Reformatez votre contenu

Pour limiter les longueurs de ligne d’un paragraphe d’un document, placez votre curseur sur le paragraphe. Ouvrez ensuite la palette de commandes et recherchez la Reflow Markdown commande. Lorsque vous sélectionnez la commande, elle met à jour les longueurs de ligne du paragraphe actuel sur la longueur configurée. Pour nos référentiels, cette longueur est de 99 caractères.

Lorsque vous utilisez cette commande pour les guillemets de bloc, assurez-vous que le paragraphe dans le guillemet de bloc que vous reflowez est entouré de lignes vides. Sinon, la commande reflowe tous les paragraphes ensemble.

Avertissement

N’utilisez pas cette commande lors de la modification d’articles. Les lignes de ces documents ne doivent pas dépasser 80 caractères. Il n’existe actuellement aucun moyen pour un référentiel de configurer différentes longueurs de ligne par dossier ou nom de fichier. Par conséquent, le reflow ne fonctionne pas pour les documents d’article.

Examiner tous les problèmes dans un document

Pour examiner toutes les violations de syntaxe et de règle de style dans un document, ouvrez l’affichage Problèmes.

Pour ouvrir l’affichage Problèmes dans l’interface utilisateur, sélectionnez « Afficher » dans la barre de menus supérieure. Sélectionnez ensuite « Problèmes » dans le menu contextuel.

Pour ouvrir l’affichage problèmes avec votre clavier, appuyez sur la combinaison de touches de votre système d’exploitation :

  • Windows et Linux : Ctrl+Maj+M
  • macOS : Cmd+Maj+M

La vue Problèmes affiche toutes les erreurs, avertissements et suggestions pour le document ouvert. Sélectionnez un problème pour s'y rendre dans le document.

Vous pouvez filtrer les problèmes par type ou correspondance de texte.

Mise à jour des métadonnées ms.date

Pour mettre à jour les ms.date métadonnées d’un article, ouvrez la palette de commandes et recherchez la Learn: Update "ms.date" Metadata Value commande. Lorsque vous sélectionnez la commande, elle met à jour les métadonnées à la date actuelle.

Ressources supplémentaires

Les tâches et les commandes décrites dans cet article ne couvrent pas tout ce que vous pouvez faire avec VS Code ou les extensions installées.

Pour plus d’informations sur l’utilisation de VS Code, consultez les articles suivants :

Pour plus d’informations sur les extensions installées, consultez leur documentation :

  • Last updated on