Ajout de la documentation

documentation/README.md

@@ -0,0 +1,26 @@
+# Zeste de Code – Documentation du Snake
+
+Ce dossier contient la documentation de la partie **Snake** (Python) des ateliers de programmation Zeste de Code, sous deux formats :
+
+- le format Markdown, prévu pour la rédaction ;
+- le format HTML, permettant la publication du guide avant l'atelier.
+
+## Licence
+
+TL;DR : **Have fun**, tout en respectant les auteurs du projet.
+
+Comme mentionné dans le README commun, cette partie est placée sous licence GNU GPL v3.0 (voir LICENCE). Ce choix est logique et découle directement de la licence du code de l'atelier ; pour rappel, cette licence impose :
+
+- le crédit des auteurs : les commentaires en début de fichier ne sauraient donc être retirés lors de la réutilisation de tout ou partie du code, sauf à obtenir l’accord particulier de l’association Zeste de Savoir ;
+- la redistribution de la source : toute modification du présent code doit être redistribuée à tous sous la même licence, afin que le partage du savoir ne se perde pas ;
+- la documentation des changements effectués : en cas de redistribution d’un code dérivé, il doit être porté mention des changements effectués, et ce afin de ne pas berner l’utilisateur.
+
+En contrepartie, vous obtenez les droits de faire ce que vous souhaitez de ce code, en particulier :
+
+- d’en faire un usage personnel ;
+- de le modifier pour réaliser votre propre atelier ;
+- de le vendre ;
+- de le partager à quiconque et sans restriction autre que celles mentionnés ci-dessus ;
+- d’expérimenter vos propres projets, et de tout casser.
+
+Dans tous les cas mentionnés, l’association Zeste de Savoir ainsi que les auteurs du code ne sauraient être tenus responsable de tous dégâts éventuels provoqués par le code, qui est distribué sans aucune garantie. De plus, ce court texte ne saurait en aucun cas se substituer au texte intégral de la licence (voir LICENCE).

documentation/manifest.json

@@ -0,0 +1,27 @@
+{
+  "type" : "TUTORIAL",
+  "object" : "container",
+  "slug" : "zeste-de-code--guide-participants--snake",
+  "title" : "Zeste de Code – Guide participants – Snake",
+  "introduction" : "introduction.md",
+  "conclusion" : "conclusion.md",
+  "children" : [ {
+    "object" : "extract",
+    "slug" : "les-bases-de-python",
+    "title" : "Les bases de Python",
+    "text" : "les-bases-de-python.md"
+  }, {
+    "object" : "extract",
+    "slug" : "fonctions-du-jeu",
+    "title" : "Fonctions du jeu",
+    "text" : "fonctions-du-jeu.md"
+  }, {
+    "object" : "extract",
+    "slug" : "fonctions-du-serpent",
+    "title" : "Fonctions du serpent",
+    "text" : "fonctions-du-serpent.md"
+  } ],
+  "version" : 2,
+  "licence" : "Tous droits réservés",
+  "description" : "Une documentation complète des fonctions du jeu Snake à destination des participants (et organisateurs) des Zeste de Code."
+}

documentation/md/conclusion.md

@@ -0,0 +1 @@
+Nous espérons que cet atelier vous plaît, merci pour votre participation !

documentation/md/fonctions-du-jeu.md

@@ -0,0 +1,158 @@
+# Présentation générale
+
+## Déclaration de l'objet Jeu
+
+Après avoir importé la bibliothèque Zeste de Code, tu auras accès aux fonctions principales du jeu ; pour rappel, un objet Jeu est créé comme suit :
+
+```py
+mon_jeu = Jeu(initialisation, boucle)
+```
+
+Où `initialisation` et `boucle` sont deux fonctions qui doivent avoir été définies précédemment (voir la partie d'initiation au code) ; ces fonctions prendront en paramètre l'instance du jeu afin de pouvoir la modifier.
+
+## Gestion des événements
+
+### Variables passées à la boucle
+
+Lorsque le jeu est récupéré à l'intérieur de la boucle, il dispose de variables accessibles de façon directe (hors fonctions / méthodes) :
+
+- `mon_jeu.largeur`, qui contient la largeur de la fenêtre ;
+- `mon_jeu.hauteur`, qui contient la hauteur de la fenêtre ;
+- `mon_jeu.evenements`, qui contient la liste des événements déclenchés depuis le dernier tour de boucle.
+
+La variable `evenments` nous intéressera particulièrement, et nous pourrons vérifier si un certain événement est déclenché en utilisant une condition :
+
+```py
+if Evenements.QUITTER in mon_jeu.evenements:
+	print("Je veux quitter")
+```
+
+### Variables de la bibliothèque
+
+Dans la suite de ce guide, nous te présenterons les fonctions ayant attrait à la zone de jeu et au serpent. Toutefois, certains objets transcendent et ne peuvent aller dans aucune des deux catégories ; ces objets sont importés par défaut et ne requièrent donc pas l'appel par une méthode.
+
+Le premier objet concerne la gestion des événements, et est naturellement nommé `Evenements` ; nous l'avons vu ci-dessus sans bien comprendre à quoi il correspondait ; cet objet contient deux variantes qui nous intéressent :
+
+```py
+# Déclenché lorsque le joueur demande à fermer le jeu
+Evenements.QUITTER
+# Déclenché lorsqu'une touche est appuyée
+Evenements.TOUCHE_APPUYEE
+```
+
+### Récupération de la touche appuyée
+
+Une fois l'événement de `TOUCHE_APPUYEE` intercepté, il serait bon de savoir sur quelle touche le joueur a appuyé afin de déplacer le serpent dans la bonne direction ; pour cela, il suffit de tester `mon_jeu.evenements[Evenement.TOUCHE_APPUYEE]`, magique non ? La valeur peut alors être égale à (notons la seconde variable interne de la bibliothèque : `Touches`) :
+
+```py
+Touches.FLECHE_DROITE
+Touches.FLECHE_GAUCHE
+Touches.FLECHE_HAUT
+Touches.FLECHE_BAS
+Touches.ESPACE
+```
+
+Pas plus de détails ici afin de vous faire chercher par vous-même ; n'oublie pas en tout cas qu'en informatique, il faut tester, tu ne peux rien casser. En cas de problème persistant, un animateur sera heureux de te guider.
+
+# Ajout d'images et de texte
+
+## Déclaration des variables internes
+
+Une fois l'objet de jeu créé, et récupéré dans une des fonctions `initialisation` ou `boucle`, il est possible de déclarer à tout moment une image par la méthode `ajouter_image`, appelée avec le nom à donner à l'image ainsi que le chemin relatif de l'image. Par la suite, on pourra afficher notre image où on veut dans la fenêtre en l'appelant par son nom (voir un peu plus loin comment faire).
+
+[[information]]
+| Le chemin relatif d'un fichier est l'endroit où il se trouve par rapport au fichier actuel. Par exemple, l'image `image.png` située dans le dossier `images` du dossier du fichier actuel est de chemin relatif `images/image.png`.
+
+Puisqu'un exemple vaut mieux qu'un long discours :
+
+```py
+# Déclaration de l'image du cactus
+mon_jeu.ajouter_image("Cactus", "images/cactus.png")
+```
+
+La méthode permettant d'ajouter du texte fonctionne de la même façon, mais prend comme second paramètre le texte à afficher ; elle est nommée `ajouter_texte`.
+
+## Récupération et dessin
+
+Afin de dessiner une image ou un texte précédemment déclaré, il faut faire appel à la fonction `dessin` ; cette fonction prend en paramètre :
+
+1. le nom déclaré de l'image ou du texte ;
+2. un objet de paramètres, pouvant prendre deux clefs : `position` et `rotation`, **toute valeur différente sera ignorée**.
+
+Par exemple, pour dessiner un cactus (déclaré précédemment), en haut à gauche de l'écran, il suffit d’appeler la fonction :
+
+```py
+mon_jeu.dessiner("Cactus", { "position": (0, 0) })
+```
+
+Une autre fonction de dessin utile est la fonction `effacer_ecran`, qui permet d'effacer entièrement le contenu de la zone de jeu ; elle ne prend aucun paramètre en entrée :
+
+```py
+mon_jeu.effacer_ecran()
+```
+
+# Gestion des positions et collisions
+
+## Itérateur principal
+
+Dès le second objectif, vous aurez besoin de réaliser une boucle sur l'ensemble de la grille du jeu ; pour cela, un itérateur `grille` existe, et donne la position (x, y) d'un morceau de grille à chaque itération ; pour bien comprendre, voici un petit exemple d'utilisation :
+
+```py
+for carreau in mon_jeu.grille():
+	print(carreau)
+```
+
+Ce code affichera la liste de tous les carreaux possibles dans la console.
+
+## Fonctions utiles
+
+Afin de vérifier une collision entre deux objets, il existe une fonction `collision` qui renvoie `True` lorsqu'il y a collision et `False` sinon. Cette fonction prend deux paramètres, la position du premier objet, et la position du second ; cette fonction est principalement destinée à être utilisée dans des conditions, par exemple :
+
+```py
+if mon_jeu.collision(pomme, morceau.position):
+	print("Collision Serpent-Pomme")
+```
+
+Vérifiera s'il y a collision entre la pomme et la variable nommée `morceau.position`.
+
+Afin d'afficher les cactus sur un bord, tu pourrais avoir besoin de savoir si une position correspond ou non à un bord, pour cela, une fonction `est_un_bord` existe, et prend comme unique paramètre la position à tester ; elle retourne un booléen. Pas d'exemple ici, on vous laisse essayer d'utiliser cette fonction par vous-même afin de bien comprendre son principe.
+
+## Divers
+
+Enfin, si tu es très avancé, tu pourras essayer d'afficher une pomme à l'écran et faire en sorte que le serpent puisse la manger. Pour générer la position de la pomme, deux solutions sont possibles :
+
+- la solution simple, utiliser `position_aleatoire_pomme`, fonction intégrée retournant simplement une position (x, y) aléatoire bien choisie ;
+- la solution plus complexe, qui consiste à créer cette fonction par toi-même ; nous donnerons évidemment des indices aux participants arrivant jusqu'ici.
+
+L'idée est de commencer par utiliser la fonction intégrée puis éventuellement de la (re)coder soi-même par la suite.
+
+# Fonctions diverses et bonus
+
+Cette partie regroupe les fonctions qui ne trouvent leur place nulle part ailleurs ; l'une d'entre elle est très utile, les autres sont des bonus destinés aux participants les plus avancés.
+
+## Quitter le jeu
+
+La fonction très utile mentionnée ci-dessus est la fonction `quitter`, qui fermera simplement le jeu ; il sera nécessaire de l'utiliser lors de l'appui sur la croix de fermeture par le joueur, ou à la mort du serpent... éventuellement ;) .
+
+## Fonctions bonus
+
+Quelques détails du jeu vous ont été cachés dans les parties précédentes, mais les objectifs bonus nous obligent à révéler certains de nos secrets les mieux gardés.
+
+Tout d'abord, la fonction d'initialisation prend en réalité non pas deux mais bien quatre paramètres ; il est en effet possible de changer la taille de la fenêtre de jeu en passant en paramètres la largeur puis la hauteur, par exemple :
+
+```py
+mon_jeu = Jeu(initialisation, boucle, 1024, 576)
+```
+
+créera une fenêtre plus grande que celle par défaut.
+
+[[attention]]
+| Il faudra veiller à ce que les deux paramètres de largeur et de hauteur soient des multiples de 32, sinon... à toi de tester.
+
+La deuxième fonction utile pour les bonus permet d'afficher du texte en plus grand que celui par défaut ; il s'agit de la fonction `init_text`. Cette méthode est pour être exact déjà appelée lors de l'initialisation du jeu (mais masquée, bien entendu). Elle permet de régler la police et la taille du texte ; un exemple pour comprendre :
+
+```py
+init_text("sans-serif", 32)
+```
+
+Cet appel rendra le texte en police sans-serif, et en taille 32, ce sont d’ailleurs les paramètres par défaut.

documentation/md/fonctions-du-serpent.md

@@ -0,0 +1,96 @@
+# Présentation générale
+
+## Déclaration de l'objet Serpent
+
+Après avoir importé la bibliothèque Zeste de Code, tu auras accès aux fonctions concernant le serpent. Une nouvelle instance de serpent devra ensuite être créée, préférentiellement à l'intérieur du jeu :
+
+```python
+def init(jeu):
+	jeu.serpent = Serpent()
+```
+
+## Constantes du serpent
+
+Dans l'objet Serpent précédemment créé, en plus des méthodes mentionnées ci-dessous, tu trouveras trois constantes (variables qui ne changent pas) importantes.
+
+### Gestion de la direction
+
+La première, `jeu.serpent.DIRECTIONS` permet de donner au serpent une direction ; elle est particulièrement utilisée avec la fonction `deplacer`, qui la prend en argument. Cet objet se décline en cinq clefs :
+
+```python
+# Le serpent va vers la droite
+jeu.serpent.DIRECTIONS.DROITE
+# Le serpent se déplace à gauche
+jeu.serpent.DIRECTIONS.GAUCHE
+# Le serpent monte
+jeu.serpent.DIRECTIONS.HAUT
+# Le serpent part en bas
+jeu.serpent.DIRECTIONS.BAS
+# Le serpent s'arrête (pas tout à fait une direction)
+jeu.serpent.DIRECTIONS.STOP
+```
+
+### Gestion des rotations
+
+Pour les plus avancés d'entre vous, il sera nécessaire de détecter quand le serpent tourne et dans quel sens. C'est à cet effet qu'a été créé la constante `ROTATIONS` :
+
+```python
+# Le serpent tourne dans le sens des aiguilles d'une montre
+jeu.serpent.ROTATIONS.HORAIRE
+# Le serpent tourne dans le sens inverse
+jeu.serpent.ROTATIONS.ANTI_HORAIRE
+```
+
+### Parties du serpent
+
+Le serpent se décompose automatiquement en diverses partie :
+
+- une tête, pour indiquer l'avant ;
+- une queue, pour indiquer l'arrière ;
+- le reste est composé de morceaux de corps.
+
+Afin de détecter ces différentes parties, une constante `jeu.serpent.PARTIES` existe, et peut prendre les valeurs suivantes :
+
+```python
+# Renseigne la tête du serpent (donc l'avant)
+jeu.serpent.PARTIES.TETE
+# Renseigne une partie de corps du serpent
+jeu.serpent.PARTIES.CORPS
+# Renseigne la queue du serpent (donc l'arrière)
+jeu.serpent.PARTIES.QUEUE
+```
+
+Notons que lors de l'itération, les parties sont ordonnées dans le sens inverse (et si tu ne comprends rien à cette phrase, reviens plus tard).
+
+Lorsque le serpent grandit, la bibliothèque ajoute automatiquement un morceau de corps juste après la tête, ce qui a pour effet de l'allonger.
+
+# Déplacement et taille
+
+Dans cette partie sont détaillées les fonctions concernant la taille du serpent ainsi que la gestion de ses déplacements.
+
+## Taille du serpent et agrandissement
+
+En premier lieu, voyons une fonction très utile, qui permet d'obtenir la taille du serpent : `serpent.taille()`. Cette fonction ne nécessite aucun paramètre ; elle retourne simplement la taille brute du serpent. Par exemple, au début du jeu, elle renverra 3.
+
+Pour faire grandir le serpent, nous en avons parlé plus haut, il est possible d'appeler la fonction `serpent.grandir()`. Elle ne prend aucun paramètre et ne retourne rien, mais modifie en interne la taille du serpent en ajoutant en morceau juste après la tête.
+
+## Fonction de déplacement
+
+Afin de déplacer le serpent, il faut appeler la méthode `serpent.deplacer(direction)` avec direction une des constantes de direction vue ci-dessus. Par exemple, pour déplacer le serpent d'une case vers le haut :
+
+```python
+serpent.deplacer(jeu.serpent.DIRECTIONS.HAUT)
+```
+
+# Position du serpent
+
+Un itérateur existe et permet d'obtenir tous les morceaux de serpent dans l'ordre allant de la queue à la tête, il s'agit de `serpent.morceaux(taille)` ; le seul argument est la taille du serpent, ou plus simplement le nombre de morceaux à prendre. Pour afficher les positions successives du serpent :
+
+```python
+for morceau in jeu.serpent.morceaux(taille):
+	print(morceau.position)
+```
+
+Comme tu peux le voir, morceau contient une information `position`, mais aussi une information `direction_rotation`, qui contient une des constantes de rotation vue ci-dessus, et enfin `type`, qui contient une constante de partie du serpent (tête, queue ou corps).
+
+Pour obtenir la position de la tête du serpent, une fonction peut te simplifier la vie, c'est la fonction `serpent.position_tete`, qui retourne simplement la position (x, y) de la tête du serpent.

documentation/md/introduction.md

@@ -0,0 +1 @@
+Ce document est une documentation complète des fonctions de la bibliothèque de l'atelier Zeste de Code ; n'hésitez pas à vous référer à lui afin de *rechercher une fonctionnalité*. Si quelque chose ne vous semble pas clair, vous pouvez toujours *appeler un animateur*, qui viendra alors vous aider.