Tutoriels dans Cloud Shell

Cloud Shell prend en charge la création et le lancement de tutoriels pour aider les utilisateurs à se familiariser rapidement et efficacement avec votre projet.

Un tutoriel est un ensemble d'instructions étape par étape au format Markdown. Cloud Shell crée des tutoriels contextualisés à partir de ces fichiers Markdown en décomposant leur contenu en étapes et sous-étapes, et en affichant celles-ci dans le panneau de droite de la console Google Cloud.

Tutoriel ouvert

En savoir plus sur les tutoriels

Pour en savoir plus sur les fonctionnalités décrites sur cette page, lancez le tutoriel interactif sur la rédaction de tutoriels en cliquant sur le bouton ci-dessous.

Ouvrir dans Cloud Shell

Rédiger un tutoriel

Les tutoriels sont écrits au format Markdown (plus précisément au format CommonMark, sans HTML) et peuvent être développés à l'aide de n'importe quel éditeur de texte. Pour les rendre plus faciles à suivre, vous pouvez également ajouter des instructions incluant des fonctionnalités avancées, telles que la mise en surbrillance et l'insertion d'icônes dans le texte. Pour ajouter une instruction, utilisez le format d'élément personnalisé suivant :

<walkthrough-directive-name param="optional parameter">
</walkthrough-directive-name>

Créer des étapes

Lors de la création d'un tutoriel, les titres sont particulièrement importants afin de déterminer sa structure. Pour définir les bons titres et en-têtes d'étapes, et les instructions sous-jacentes, suivez la hiérarchie ci-dessous :

  • Balises H1 (#) pour le titre du tutoriel (il ne devrait y avoir qu'une seule balise H1 dans le tutoriel)
  • Balises H2 (##) pour un titre d'étape
  • Balises H3 (##) pour un titre de sous-étape

Voici un exemple de fichier Markdown que vous pouvez utiliser pour créer un tutoriel :

# First Tutorial

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

Ajouter un bloc de code

Pour faire apparaître un extrait de code, encadrez-le d'accents graves, comme suit :

```
print("hello world")
```

L'extrait de code obtenu est accompagné d'un bouton "Copier dans le presse-papiers" situé dans l'angle droit.

Créer un effet de surbrillance

Un effet de surbrillance est une aide visuelle destinée à guider l'attention des utilisateurs sur un élément d'interface utilisateur spécifique de la console Cloud Platform.

Pour mettre en évidence un élément de la console Cloud Platform, utilisez ce format :

<walkthrough-spotlight-pointer spotlightId="target" text="label text">
</walkthrough-spotlight-pointer>

Ainsi, si vous souhaitez mettre en surbrillance le bouton permettant d’ouvrir la fenêtre d’aperçu sur le Web de Cloud Shell, utilisez :

<walkthrough-spotlight-pointer spotlightId="devshell-web-preview-button"
                               text="Open Cloud Shell">
</walkthrough-spotlight-pointer>

Voici la liste de toutes les cibles possibles pour l'effet de surbrillance :

Cibles de l'effet de surbrillance dans Cloud Console Description
devshell-activate-button Bouton permettant d'ouvrir Cloud Shell, en haut à droite.
devshell-web-editor-button Bouton permettant d'ouvrir l'éditeur Orion, dans la barre supérieure de Cloud Shell.
devshell-web-preview-button Bouton permettant d'ouvrir Ouvre une fenêtre d'aperçu sur le Web pour Cloud Shell.

Pour mettre en surbrillance un élément de l'éditeur Cloud Shell, suivez le format ci-dessous :

<walkthrough-editor-spotlight spotlightId="target" text="label text">
</walkthrough-editor-spotlight>

En utilisant le format ci-dessus et la commande editor-spotlight, vous pouvez créer un effet de surbrillance sur un fichier hello.md existant, qui s'active lorsqu'un utilisateur clique sur "My file" (Mon fichier). Procédez comme suit :

<walkthrough-editor-spotlight spotlightId="navigator" filePath="hello.md"
                              text="My file">
</walkthrough-editor-spotlight>

Autres cibles possibles pour l'effet de surbrillance dans l'éditeur :

Cibles de l'effet de surbrillance dans l'éditeur Description
fileMenu Met en surbrillance le bouton du menu "Fichier".
editMenu Met en surbrillance le bouton du menu "Édition".
navigator Met en surbrillance un fichier spécifié.

Insérer une icône dans un texte

Pour illustrer efficacement l'utilité d'un bouton de Cloud Console, insérez son icône dans le texte de vos tutoriels.

Les icônes suivantes sont disponibles :

Instruction Description
`walkthrough cloud-shell-icon` Icône Cloud Shell
`walkthrough web-preview-icon` Icône "Aperçu sur le Web"
`walkthrough cloud-shell-editor-icon` Icône "Éditeur Cloud Shell"

Déclencher des actions de fichier

Votre tutoriel peut également contenir des liens qui ouvrent des fichiers pertinents pour les utilisateurs. Pour ouvrir un fichier dans Cloud Editor lorsque votre utilisateur parcourt un tutoriel et clique sur le texte "Ouvrir un fichier exemple", utilisez l'instruction suivante :

<walkthrough-editor-open-file filePath="path/to/test.md"
                              text="Open sample file">
</walkthrough-editor-open-file>

Remarque : Le fichier doit exister sur l'instance Cloud Shell des utilisateurs, et le chemin de fichier fourni doit lui être associé. Le fichier doit, en outre, être situé dans le répertoire d’accueil ou dans l'un de ses sous-répertoires.

Démarrer des tutoriels dans Cloud Shell

Il existe trois façons de démarrer un tutoriel dans Cloud Shell :

  1. Utilisez la commande teachme

    Exécutez la commande suivante dans votre session Cloud Shell pour démarrer un tutoriel à partir d'un fichier existant, hello.md :

    teachme hello.md
    
  2. Utilisez "Ouvrir dans Cloud Shell"

    Vous pouvez également utiliser la fonctionnalité Ouvrir dans Cloud Shell pour guider vos utilisateurs depuis un site Web, un blog ou un projet Open Source vers votre tutoriel. Celle-ci permet de spécifier un paramètre "tutorial" et peut être ajoutée à la fin de l'URL. Par exemple : &tutorial=path/to/file.md. Ainsi, l'expression Markdown pour un bouton associé à votre tutoriel ressemblerait à ceci :

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/testuser/myproject&tutorial=resources/hello.md)
    
  3. Utilisez la commande cloudshell launch-tutorial

    Exécutez la commande cloudshell suivante dans votre session Cloud Shell afin de démarrer un tutoriel à partir d'un fichier Markdown existant, tutorial.md :

    cloudshell launch-tutorial tutorial.md
    

Étapes suivantes

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…