License : Creative Commons Attribution 4.0 International (CC BY-NC-SA 4.0)
Copyright : Jérémy Fix, Hervé Frezza-Buet, CentraleSupelec
Last modified : March 29, 2024 01:04
Link to the source : index.md

Table of contents

Tutoriel pour vos énoncés

Objectif

Le but est de nous simplifier l’édition et la mise en ligne de TP, ou autre documents pédagogique. En plus, on aura par défaut une présentation uniforme de nos contenus.

Certains contenus sont utilisés dans plusieurs formations, par exemple le tuto git, et il est bon dans ce cas, pour chaque formation, de références toujours les mêmes contenus.

Les outils

Git et pandoc

Il faut maîtriser git, les bases du moins, on donne (ce tuto si besoin) aux élèves. Il faut aussi disposer de la commande make.

Nous allons nous baser sur pandoc pour générer les pages web. C’est un langage de “markup” qui permet de faire des pages html, avec du latex dedans pour les formules, du code bien mis en forme, etc…

Organisation des fichiers

Sur votre dépôt GIT à vous, sur gitlab-research.centralesupelec.fr (ou sur un autre gitlab, sur github, c’est un peu différent), disons que vous voulez créer un TP “Philatelie”. Créez ce dossier ‘TP-Philatelie’. Allez dedans, et créez un fichier index.md, qui contient

---
title: test
...

# Introduction à la Philatélie

Il va falloir en faire une page web. Pour ce faire, il faut, dans ce dossier toujours, ramener du matériel. Tapez :

mylogin@mymachine:~$ wget https://fix_jer.pages.centralesupelec.fr/tutorials/mdstyle.tar.gz --no-check-certificate
mylogin@mymachine:~$ tar zxvf mdstyle.tar.gz
mylogin@mymachine:~$ rm mdstyle.tar.gz

Cette commande vous a rajouté un fichier ‘Makefile’ et un dossier ‘templates’. Attention, ne les versionnez pas.

Vous pouvez maintenant fabriquer votre site web. Au préalable (à ne faire qu’une fois sur votre machine), assurez-vous de bien avoir tous les packages.

mylogin@mymachine:~$ make install-deps

Une fois que c’est fait, à chaque fois que vous voulez regénérer votre site :

mylogin@mymachine:~$ make all

Votre site est dans le dossier build, qu’il ne faut pas versionner non plus. Pour voir ce que ça rend:

mylogin@mymachine:~$ firefox build/index.html

Vous aurez besoin de proposer des contenus, de type images, fichiers à télécharger pour les élèves, etc… Mettez les dans un dossier ‘data’. Contrairement aux autres, il vous faudra versionner ce dossier.

Donc pour résumer, chez moi, pour le tuto que vous êtes en train de lire:

mylogin@mymachine:~$ pwd
/home/herve/Git/tutorials/Meta-Tuto
mylogin@mymachine:~$ ls
build  data  index.md  Makefile  templates

et seuls data/ et index.md sont versionnés.

En fin de tuto, on présentera la syntaxe de pandoc, parce que pour l’instant, à part un titre, vous n’avez pas grand’ chose.

Déployer son site

L’idée maintanant est de rendre votre site public, et donc référençable par vos pages pédagogiques (moodle, sdi.metz, etc…). Nous allons pour cela utiliser les services ci (continuous integration) de gitlab. L’idée, à chaque fois que vous commiterez un changement dans le dossier ‘Philatelie’, c’est que le serveur gitlab regénère les pages web chez lui, et les pose à un endroit où elles sont accessibles à tous.

Pour piloter ce comportement, il faut que vous ayez (ou que vous augmentiez s’il existe déjà), un fichier nommé ‘.gitlab-ci.yaml’ à la racine de votre repository git. Ca s’édite avec un éditeur de texte en mode text (de base). Attention !, il ne faut pas qu’il y ait le moindre caractère TAB dans le fichier, et les éditeurs de texte en insèrent parfois quand ils vous alignent les éléments d’une liste par exemple.

A titre d’exemple, on vous donne un fichier yaml .gitlab-ci.yml qui fait le job. Inspirez-vous en. Seule la partie “TP-xxx” est à modifier, et à dupliquer pour chacun des TPs que votre dépôt fournit. Ici, il faudra remplacer xxx par Philatelie.

Quand vous commiterez des modifications dans TP-Philatelie, gitlab invoquera des “pipelines” pour construire votre site web sur le serveur, comme vous-même l’avez fait dans build. Le lien sur le site est <le_login_du_proprietaire>.pages.centralesupelec.fr/TPs/TP-Philatelie/index.html (sous réserve que votre dépot se trouve sur gitlab-research).

Ce lien est utilisable par vos pages de cours. Par exemple, sur sdi.metz.centralesupelec.fr, on a fait des articles spip qui ne font qu’ouvrir un viewport pour visualiser ces pages (regardez la section “self-study” par exemple).

Quelques trucs de pandoc

Le fichier index.md qui a généré la page que vous êtes en train de lire peut se ramener via un lien, qui est tout en haut de cette page. Dans ce fichier, vous verrez comment on génère ce qui suit. C’est ça, le tuto pandoc. Il y a des extraits d’un “howto” de Jérémy qui sont encore en anglais.

En-tête

Ce sont les quelques lignes du début. Si vous ne voulez pas de table des matières, supprimez la ligne usetoc: true (ne mettez pas false, il faut vraiment virer la ligne).

Si vous voulez voir apparaître une barre de menu comme sur ce tutoriel, il vous suffit de mettre dans l’entête :

topmenu:
- link: page1.html
  title: Link to page1
  current: 1
- link: page2.html
  title: Link to page2
- link: http://www.centralesupelec.fr
  title: Link to CentraleSupelec

L’option “current: 1” permet d’indiquer visuellement quelle page est active dans le menu du haut.

L’entête du fichier markdown que vous êtes entrain de lire est :

---
title: Meta-Tutorial
author: 
- Jérémy Fix
- Hervé Frezza-Buet
usetoc: true
topmenu:
- link: index.html
  title: Index page
  current: 1
- link: other.html
  title: Another page
...

Hiérarchie

Pour les titres, sous-titre, sous-sous-titres, … il faut précéder le texte de #, ##, ###

Listes

Mais aussi des listes numerotés (les nombres dans le fichier .md sont bidons, on part du premier, 3 ici). Il semble que ça ne gère pas les sous-listes numérotées.

  1. Premier
  2. Deuxième
  3. Deux et demie…
  4. Deux 3/4…
  5. Troisième

Formats

On peut mettre des élements en relief, ou avec une forme de truc informatique, du genre toto.txt.

Il y a un support latex. Ci-dessous l’équation d’Euler, utilisée par exemple pour calculer \(\sin(2x) = 3 \sin(x) - 4\sin^3(x)\) : \[e^{i\pi}+1 = 0\]

On peut faire des liens, du genre google.

On peut faire des notes de bas de page1 en bas de la page.

Contenus

On peut bien sûr inclure des images

The Boy surface
The Boy surface

Biblio

Vous pouvez citer des entrées bibtex (Hua et al., 2015). Ces citations sont automatiquement insérées à la fin du document. Elles sont extraites du fichier biblio.bib et utilise l’extension citeproc de pandoc. Pour que ça marche, vous n’avez qu’à mettre un fichier de biblio nommé biblio.bib, le Makefile se charge de détecter si il existe et si il existe, d’ajouter les options pour le prendre en charge.

Codes

Les codes sont colorés avec pygmentize en utilisant le filtre pandoc pandocfilter-pygments.py.

1
2
3
4
5
6
7
8
import keras

def my_function():
   "just a test"
   print 8/2x
while(True):
   x = x + 1
print(x)

Si vous regardez la source markdown (en lien tout en haut de la page), vous verrez que le code est simplement cité entre des backquotes.

On peut aussi inclure du code contenu dans des fichiers. Ici, on dispose du fichier test.cpp, et on en affiche le contenu sur cette page

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
#include <iostream>

// This is a test class
class Test {
private:
  int i;
public:
  Test() = default;
};


int main(int argc, char* argv[]) {

  Test t;

  std::cout << "Hello world !" << std::endl;
  // Why do all test program display "Hello world !" ?
  
  return 0;
}

Bash

Utilisez le prompt ci-dessous, il apparaîtra coloré

mylogin@mymachine:~$ ls -al
total 32
drwxr-xr-x  5 herve herve 4096 avril 20 11:45 .
drwxr-xr-x 12 herve herve 4096 avril 20 11:36 ..
drwxr-xr-x  5 herve herve 4096 avril 20 11:19 build
drwxr-xr-x  2 herve herve 4096 avril 20 11:34 data
-rw-r--r--  1 herve herve 5609 avril 20 11:45 index.md
-rw-r--r--  1 herve herve 1560 avril 20 10:01 Makefile
drwxr-xr-x  2 herve herve 4096 avril 20 10:55 templates

Tikz

Use this

```
{.tikz}
\begin{tikzpicture}

\def \n {5}
\def \radius {3cm}
\def \margin {8} % margin in angles, depends on the radius

\foreach \s in {1,...,\n}
{
  \node[draw, circle] at ({360/\n * (\s - 1)}:\radius) {$\s$};
  \draw[->, >=latex] ({360/\n * (\s - 1)+\margin}:\radius) 
    arc ({360/\n * (\s - 1)+\margin}:{360/\n * (\s)-\margin}:\radius);
}

\node at (0, 0) {\includegraphics[width=0.2\textwidth]{./figs/boy.png}};
\end{tikzpicture}
```

to get

Note that if you use includegraphics, your figures must be in the figs subdirectory. This is hardcoded path in the templates/tikz.py script that is performing the rendering.

Graphs

On peut directement inclure des graphes en syntaxe graphviz dans le corps du fichier markdown.

this is the caption
this is the caption
Graph of pandoc compilation pipeline
Graph of pandoc compilation pipeline

Emoji

On peut même rajouter des Emoji 😄 C’est trop cool 😂 😜 😂 😜 Une liste complète est consultable depuis Liste des emoji. On peut même y voir ses collègues comme Jeremy :neckbeard: ou Hervé 🐙

Hua, L., Gong, S., Wang, F., Li, W., Ge, Y., Li, X., & Hou, F. (2015). Captive breeding of pangolins: Current status, problems and future prospects. ZooKeys, 507, 99–114. https://doi.org/10.3897/zookeys.507.6970


  1. C’est ça la note de bas de page.

Jérémy Fix, Hervé Frezza-Buet,