Création d’un dépôt

1. Présentation

Markdown est un langage de présentation qui gagne en popularité depuis plusieurs années, comme le montre le graphique Google Trends ci-dessous :

Source : https://trends.google.fr/trends/explore?date=all&q=markdown

Ce langage n’est pas un langage de présentation avec une structure XML comme l’est HTML. Ce langage a été conçu dans le but d’être lisible directement en mode texte, ce qui l’a rendu très populaire chez les développeurs. En effet, un format comme le Markdown peut être consulté en mode texte et donc peut facilement être versionné. Il est d’ailleurs possible d’exporter des fichiers Markdown facilement vers du code HTML ou d’autres formats.

La syntaxe officielle est documentée sur le lien suivant : http://daringfireball.net/projects/markdown/syntax

Certaines syntaxes ne sont pas officielles, mais sont généralement bien supportées par les logiciels et bibliothèques s’interfaçant avec Markdown. Elles permettent d’ajouter des fonctionnalités absentes du format officiel. Les fichiers Markdown portent généralement l’extension .md.

Voici un exemple de fichier Markdown très simple d’un jeu fictif et son affichage sur GitHub :

# Stratégiii : le meilleur de la stratégie 
 
## Fonctionnalités 
 
+ 64 unités différentes ! 
+ La **meilleure IA** jamais vue ! 

Voici la manière dont ce fichier sera affiché sous GitHub :

2. Éléments de syntaxe

1. Présentation

reStructuredText est un autre format de présentation au même titre que Markdown. Il est un peu moins populaire que Markdown, mais propose certaines options qui sont absentes de Markdown.

La documentation officielle est très complète : http://docutils.sourceforge.net/rst.html#reference-documentation

La présentation de la syntaxe de reStructuredText sera plus succincte, car il convient à des usages plus poussés que Markdown et son apprentissage dépasse le cadre de ce livre. Il convient juste de garder à l’esprit que les possibilités de reStructuredText vont bien au-delà des quelques exemples ci-dessous.

Les fichiers reStructuredText portent généralement l’extension .rst.

2. Éléments de syntaxe

Titre de niveau 1 
=================== 
 
Titre de niveau 2 
---------------------- 
 
Titre de niveau 1 
=================== 

1. Sublime Text

Ce n’est pas l’outil qui gère le mieux le Markdown, en revanche, c’est l’éditeur que de nombreux développeurs utilisent quotidiennement. Il est donc normal de vouloir l’utiliser pour écrire la documentation également. Sublime Text ne gère pas nativement le Markdown (hormis le fait que ce soit un éditeur de texte), en revanche il existe plusieurs plug-ins permettant d’éditer facilement et visuellement le Markdown.

Sublime Text est un éditeur de texte compatible avec les trois systèmes d’exploitation principaux, Linux, Mac OS et Windows.

Le plug-in Markdown Preview permet d’exporter facilement le contenu d’un fichier Markdown vers un fichier HTML. C’est un système très pratique pour versionner une documentation et partager une version plus lisible. Voir la page GitHub du produit : https://github.com/revolunet/sublimetext-markdown-preview

Le plug-in MarkdownEditing permet d’avoir une interface proposant la coloration syntaxique. Cette interface se montre plus intuitive et permet de faciliter la lecture de documents Markdown bruts.

Le plug-in MarkdownTOC (pour Markdown Table Of Content) permet d’éditer une table des matières en fonction des titres présents dans le document. L’un des avantages de ce plug-in est qu’après export en HTML (avec Markdown Preview), il est possible de cliquer sur un élément de la table des matières pour accéder à la section...

1. Configuration minimale

Cette configuration a déjà été évoquée à la fin du chapitre Installation de Git, à la section Configuration requise, cette partie sera donc très rapide. Pour utiliser Git, il est nécessaire de passer par une étape de configuration préalable. Sans celle-ci, il n’est pas possible d’utiliser Git normalement, il refusera par exemple d’enregistrer vos modifications.

Cette configuration va servir à nous identifier pour que Git sache qui effectue telle ou telle modification. Voici donc comment configurer sur le dépôt nos nom, prénom et adresse e-mail :

git config --global user.name "Prenom Nom" 
git config --global user.email email@domain.ext 

Maintenant que la configuration initiale a été définie, il est possible de travailler avec Git. Pour avoir une aide concernant la configuration et ses paramètres, il faut utiliser la commande suivante :

git config --help 

2. Niveaux de configuration

Git utilise des fichiers pour stocker les différents éléments de configuration. Lorsque nous utilisons les commandes git config, ce sont indirectement ces fichiers que nous modifions.

Il existe trois niveaux de configuration dans Git. Ces niveaux de configuration ont tous une portée...

1. Pagination

Lorsqu’on utilise des commandes comme git diff, si le résultat dépasse une page une pagination automatique sera effectuée à l’aide de less (commande UNIX affichant un texte page par page). Ce type de pagination peut déranger certains utilisateurs qui préféreraient n’avoir aucune pagination et naviguer sans contrainte dans le document. Pour cela, il faut définir une pagination de type cat :

git config --global pager = cat 

2. Expressions régulières étendues

Par défaut, Git n’active pas les expressions régulières étendues, c’est-à-dire que les métacaractères comme les accolades sont totalement ignorés. Pour ceux qui sont habitués aux expressions régulières et qui les utilisent couramment, il est préférable d’activer l’option suivante :

git config --global extendedRegexp = true 

3. Séparateur de mots

Lorsqu’on utilise git diff en mode mot (à l’aide de l’option --color-words par exemple), il peut être utile de spécifier à Git ce qu’est un mot. Par défaut, pour Git un mot est une suite de caractères séparée des autres par un ou des espaces. Or, dans une ligne de code il est possible de n’avoir aucun espace et pourtant certaines parties de la ligne sont sémantiquement différentes, c’est la raison pour laquelle il peut être utile de définir ce paramètre :

git config --global wordRegex = .{2} 

En effet, ce paramètre...