Écrire de la documentation

Comment écrire et soumettre une nouvelle doc

• Dépôt
• Si on n’est pas un informaticien
  • Éditeur en ligne
  • Éditeur classique
    • Configurer un éditeur qui va bien
    • Modifier une documentation
• Le Markdown pour les nuls

Dépôt

La documentation de thor est hébergée sur le dépôt git suivant : https://thor.enseirb-matmeca.fr/git/docs-thor

Actuellement la liste des personnes autorisées à pousser est donnée en extension, elle devrait être ouverte à tout enseignant. En attendant, merci de nous envoyer un mail à l’adresse indiquée sur la page d’accueil pour que nous rajoutions votre login a la liste (adresse accessible uniquement aux utilisateurs connectés).

Si vous êtes un étudiant, nous prenons aussi vos contributions sous la forme de pull-request. Comme nous ne sommes pas github, merci de formater vos PR avec git format-patch et de les envoyer à l’adresse précédente.

Si on n’est pas un informaticien

Éditeur en ligne

La forge propose une solution d’édition en-ligne (beta), cliquez sur le bouton éditer et allez-y.

Éditeur classique

Il vous faudra un éditeur de texte, un client git et éventuellement un outil de prévisualisation. On peut distinguer la configuration (à ne faire qu’une fois) et l’utilisation quotidienne (ou annuelle ;) ). Les sections suivantes expliquent ces deux étapes au travers d’un éditeur, atom, qui fournit tout ceci intégré.

Configurer un éditeur qui va bien

• Récupérer atom. Non pas que je sois fan de cet éditeur, mais il dispose d’un support natif pour git et d’un plug-in pour visualiser le Markdown en live, ce qui le rend tout adapté à cette mission. Bien entendu, si vous savez ce que vous faites, je vous en prie ;)

• Créer un répertoire de travail: File > Add project folder …. Choisissez un endroit bien rangé sur votre machine qui contiendra votre répertoire de travail (vos versions de la doc). Nous le lierons au dépôt officiel des docs juste après.

• Activer la gestion de version : View > Toggle git tab. Puis initialiser votre nouveau dossier comme un dépôt en cliquant sur le bouton Create repository. Validez le choix proposé.

• (Une procédure plus simple ?) Éditez le fichier .git/config et collez le texte suivant dedans (en pensant à remplacer le fmorandat par votre login)

  [remote "origin"]
    url = https://fmorandat@thor.enseirb-matmeca.fr/git/docs-thor
    fetch = +refs/heads/*:refs/remotes/origin/*
  [branch "master"]
    remote = origin
    merge = refs/heads/master
  

• Et maintenant je suis embêté car ma version d’atom est pourrie et mon bouton fetch pas là, donc je vais supposer. En bas à droite une icône fetch est apparue. Cliquez dessus pour récupérer les dernières versions de la doc.

• Et voilà! La configuration d’atom est faite, tant que vous resterez sur votre machine, vous n’aurez plus a le refaire. Vous pouvez maintenant modifier votre première doc pour tester.

Modifier une documentation

• Editez un fichier (double Cliquez dessus dans la barre de gauche).
• Activer la live preview : Control-Shift-M (ou Packages > Markdown Preview > Toggle Preview)
• Modifier son contenu
• Dans l’onglet Git (a droite), le fichier que vous venez de modifier apparait dans la catégorie Unstaged changes (pas encore prise en compte)

• Cliquez dessus et il vous montre le changement (en rouge enlevé, en vert ajouté). Si vous êtes content de votre travail, ajouter vos modifications en cliquant sur Stage file (voire Stage all dans la fenêtre de droite).

• Ajoutez un commentaire sur votre travail qui explique ce que vous avez fait : Exemple: Rajouté section pour le cas des étudiants étrangers. Les règles de bien séance pour les messages sont : une ligne qui résume ce que vous venez de faire (autour de 50 car. maximum) sans le point final. Puis, si nécessaire, laissez une ligne blanche et racontez ce que vous avez a raconter sur ce changement.

• Cliquez sur commit to master pour valider vos changement (attention il ne sont toujours pas transmis)

• Transmettez vos changement en cliquant sur push en bas à droite. Si tout va bien on s’arrête là, on va voir sa magnifique doc sur thor et on est content.

• Sinon il va falloir régler le conflit … et j’écrirai cette section un autre jour.

Le Markdown pour les nuls

• Une phrase => une ligne.
• blabla
• Kramdown Syntax
• C’est génial ou pas