Syntaxe Rest

  • Auteurs :
    • NicolasJoubert
  • Version : 1.0

  • Date de création :

    04/02/2015

  • Modification : Pas de modification

  • Status : En cours d'écriture

  • Relectures :
    Relu par :
    • Non relu
  • Validation :
    Validé par :
    • Non validé
  • Destinataire :

  • Commentaires :

  • Vie du document :
    • 1.0 :

      Version initiale

      04/02/2015


1   Ecriture en REST

1.1   Principe

Tant que l'on reste avec un meme niveau d'indentation (par exemple pas d'indentation du tout ), le texte est écrit toujours avec la même position par rapport à la marge gauche. Un simple retour chariot ne constitue pas un changement de paragraphe. Le texte est collé à la suite du texte precédent, en remplacant le retour chariot par un espace.

Pour changer de paragraphe, il faut insérer une ligne vide.

Peut importe le nombre de ligne vides insérées. La signification est toujours la même : fin du bloc courant. Si on tape une série de retour chariot, seul le premier est pris en compte. Les autres seront ignorés.

1.2   Gestion de l'indentation

L'indentation permet d'augmenter ou de diminuer espace à gauche du texte.

Cette indentation est mise en place par des espaces ou des tabulations en debut de texte.

Comme pour le retour chariot, la seule chose qui compte, c'est l'indentation relative :
  • Peut importe le nombre d'espace mis avant le paragraphe. Ils seront remplacés par un espace fixe.
  • Si le parragraphe qui suit à une indentation supérieure ( peut importe de combien ), il sera placé plus à droite que le précédent, et la valeur du décalage serra indépendant de la valeur de l'indentation.

Pas d'indention

un espace avant le texte

deux espaces : remarque. Pas besoin de retour chariot si on change l'indentation. Il est automatique. Tant que je ne met pas de retour chariot, cela fonctionne.

trois espaces

quatre espace

une tabulation ou huit espaces

douze espaces

deux tabulation ou seize espaces

douze espaces

Chaque indentation défini un nouveau bloc de texte. La marque de fin de bloc est donnée par une ligne vide.

L'écriture d'un texte en rest fonctionne sur le principe de bloc. Suite de l'écriture dans le bloc 1

Un bloc continu tant que l'indentation reste identique. Un changement d'indentation change l'appartenance au bloc.

Bloc indent etrange. Et rebloc

Un autre bloc Mais avec des tabulations

Meme indentation à l'interieur du bloc

Suite du bloc Retour à la ligne simple

Retour à la ligne double

Un bloc intermédiaire

Retour à la marge gauche. Retour chariot simple

Attention à l'aspect visuel de la tabulation. En REST, une tabulation = 8 espaces.

1.3   Les commentaires

Il est possible d'insérer du commentaire dans le source de la doc. Ces commentaires n'apparaitrons pas dans le texte généré.

Code Résultat
..
  Ce grand block indenté
  est un commentaire.

  Toujours dans le commentaire,
  car indenté de la meme maniere.

1.4   Les sections

Code Résultat
Titre
=====
Soustitre
---------
Les titres sont soulignés (ou
surlignés et soulignés) avec un
caractére ASCII 7-bit non
alphanumérique. Les valeurs
recommandées sont
"``= - ` : ' " ~ ^ _ * + # < >``".
Les surlignement/souslignements
doivent être au moins aussi long que
le texte du titre.

Titre

Soustitre

Les titres sont soulignés (ou surlignés et soulignés) avec un caractére ASCII 7-bit non alphanumérique. Les valeurs recommandées sont "= - ` : ' " ~ ^ _ * + # < >". Les surlignement/souslignements doivent être au moins aussi long que le texte du titre.

1.5   Les mises en valeurs

Code Résultat Note
*italique*
italique  
**gras**
gras  
`citation courte`
citation courte  
``texte brut``
texte brut  
reference_
reference

Pour que le lien fonctionne, il faut mettre la directive suivante :

.. _reference: http://docutils.sourceforge.net/spec/rst/reStructuredText.html
`phrase de reference`_
phrase de reference

Pour que le lien fonctionne, il faut mettre la directive suivante :

.. _`phrase de reference`: http://docutils.sourceforge.net/spec/rst/reStructuredText.html
anonyme__
anonyme

Pour que le lien fonctionne, il faut mettre la directive suivante :

.. __: http://docutils.sourceforge.net/spec/rst/reStructuredText.html

1.6   Les liens

1.6.1   Externes
Code Résultat Note
Hyperlien externe, Python_ par exemple.

.. _python: http://www.python.org/

Forme condensée

Hyperlien externe, Python par exemple.

Forme explicite

Hyperlien externe, Python par exemple.

Python : http://www.python.org/

Hint

La forme condensée est la représentation utilisée dans les documents HTML, tandis que la forme explicite est plus adaptée pour les documents imprimés, où le lien doit rester visible, par exemple dans une note de bas de page

1.6.2   Internes
Code Résultat
Référence interne, par exemple_.

.. _exemple:

Ceci est un exemple de cible de
référence interne au document.

Forme condensée

Référence interne, par exemple.

Ceci est un exemple de cible de référence interne au document.

Forme explicite

Référence interne, par exemple.

exemple:

Ceci est un exemple de cible de référence interne au document.

1.6.3   Indirect
Code Résultat Note
Python_ est `mon langage de
langage de programmation favori`__.

.. _Python: http://www.python.org/

__ Python_
Python est mon langage de programmation favori.

Hint

La seconde cible d'hyperlien (la ligne qui commence par "__") est à la fois une cible d'hyperlien indirect (qui pointe indirectement sur le site web Python via la référence "Python") et une cible d'hyperlien anonyme. Dans le texte, une terminaison en double souligné est utilisée pour indiquer une référence à un hyperlien anonyme. Dans une cible d'hyperlien anonyme, le texte de référence n'est pas répété. Ceci est utile pour les références avec un texte long ou pour les références jettables, mais la cible doit rester proche de la référence pour éviter une désynchronisation.

1.6.4   Implicites
Code Résultat
Les titres sont des cibles implicites
=====================================

Les réferences implicites, comme
`Les titres sont des cibles
implicites`_.

Les titres sont des cibles implicites

Les réferences implicites, comme Les titres sont des cibles implicites.

1.7   Les telechargements

Code Résultat
Telechargement de pre-pam_mount__

__ attachment:pre-pam_mount.sh

Telechargement de

pre-pam_mount.sh

1.8   Les listes

1.8.1   De type puce
Code Résultat
Listes à puces:

- Voici le premier élément
- Voici le second élément

- Les puces sont "-", "*" ou "+".

Remarquez qu'une ligne vide est
nécéssaire avant le premier élément et
aprés le dernier, mais n'est pas
obligatoire entre les éléments.

Listes à puces:

  • Voici le premier élément
  • Voici le second élément
  • Les puces sont "-", "*" ou "+".

Remarquez qu'une ligne vide est nécéssaire avant le premier élément et aprés le dernier, mais n'est pas obligatoire entre les éléments.

1.8.2   De type numéroté
Code Résultat
Listes numérotées:

3. Voici le premier élément
4. Voici le deuxième élément
5. La numérotation peut être faite en
   chiffres arabes, en lettres ou en
   chiffres romains.
6. Les listes numérotées doivent
   l'être de façon séquentielle, mais
   il n'est pas nécéssaire qu'elles
   débutent à 1 (cependant tous les
   formatteurs ne respecteront pas le
   premier indice).

Listes numérotées:

  1. Voici le premier élément
  2. Voici le deuxième élément
  3. La numérotation peut être faite en chiffres arabes, en lettres ou en chiffres romains.
  4. Les listes numérotées doivent l'être de façon séquentielle, mais il n'est pas nécéssaire qu'elles débutent à 1 (cependant tous les formatteurs ne respecteront pas le premier indice).
1.8.3   De type définitions
Code Résultat
Listes de définitions:

quoi
  Les listes de définitions associent
  un terme à sa définition.

comment
  Le terme est une phrase d'une ligne
  et la définition est composée d'un
  ou plusieurs paragraphes ou éléments
  de texte, décalés à droite par
  rapport au terme à définir. Les

  Les lignes vides ne sont pas
  autorisées entre le terme et sa .
  définition

Listes de définitions:

quoi
Les listes de définitions associent un terme à sa définition.
comment

Le terme est une phrase d'une ligne et la définition est composée d'un ou plusieurs paragraphes ou éléments de texte, décalés à droite par rapport au terme à définir. Les

Les lignes vides ne sont pas autorisées entre le terme et sa . définition

1.8.4   De type champs
Code Résultat
Listes de champs:

:Auteur:
   Tony J. (Tibs) Ibbs,
   David Goodger

   (et divers d'autres personnes de
   bonne composition)

:Version: 1.0 du 2001/08/08
:Dédicace: A mon pére.

Listes de champs:

Auteur:

Tony J. (Tibs) Ibbs, David Goodger

(et divers d'autres personnes de bonne composition)

Version:

1.0 du 2001/08/08

Dédicace:

A mon pére.

1.8.5   De type options
Code Résultat
-a            option "a"
-b file       les options peuvent
              avoir des arguments et
              de longues descriptions
--long        les options peuvent aussi
              avoir des noms longs
--input=file  les options avec des
              noms long peuvent aussi
              avoir de longues
              descriptions
/V            Les options à la mode
              DOS/VMS fonctionnent
              aussi
-a option "a"
-b file les options peuvent avoir des arguments et de longues descriptions
--long les options peuvent aussi avoir des noms longs
--input=file les options avec des noms long peuvent aussi avoir de longues descriptions
/V Les options à la mode DOS/VMS fonctionnent aussi

Il doit y avoir au moins deux espaces entre l'option et sa description.

1.9   Les images

L'insertion d'image ne pose pas de problèmes particuliers.

Code Résultat
.. figure:: games-hint.png
 :scale: 200

 Ceci est une figure
games-hint.png

Ceci est une figure

.. image:: tools-wizard.png
 :scale: 50
 :width: 50
 :height: 50
 :align: left
tools-wizard.png
.. image:: tools-wizard.png
 :scale: 50
 :width: 50
 :height: 50
 :align: center
tools-wizard.png
.. image:: tools-wizard.png
 :scale: 50
 :width: 50
 :height: 50
 :align: right
tools-wizard.png
Une image |image1| au coeur du texte

.. |image1| image:: games-hint.png
Une image image1 au coeur du texte

1.10   Les tableaux

Code Résultat
Grille :

+----------+-----------+----------------+
| Entête 1 | Entête 2  | Entête 3       |
+==========+===========+================+
| rang 1   | colonne 2 | colonne 3      |
+----------+-----------+----------------+
| rang 2   | Cellule étendue en ligne   |
+----------+-----------+----------------+
| rang 3   | Cellule   | - Les cellules |
+----------+ étendue   | - contiennent  |
| rang 4   | en colonne| - des blocs.   |
+----------+-----------+----------------+


Tableau simple :

=====  =====  ======
   Entrée     Sortie
------------  ------
  A      B    A ou B
=====  =====  ======
Faux   Faux   Faux
Vrai   Faux   Vrai
Faux   Vrai   Vrai
Vrai   Vrai   Vrai
=====  =====  ======

Grille :

Entête 1 Entête 2 Entête 3
rang 1 colonne 2 colonne 3
rang 2 Cellule étendue en ligne
rang 3 Cellule étendue en colonne
  • Les cellules
  • contiennent
  • des blocs.
rang 4

Tableau simple :

Entrée Sortie
A B A ou B
Faux Faux Faux
Vrai Faux Vrai
Faux Vrai Vrai
Vrai Vrai Vrai

1.11   Les directives

Code Résultat
.. attention:: note

.. caution:: note

.. danger:: note

.. error:: note

.. hint:: note

.. important:: note

.. note:: note

.. tip:: note

.. warning:: note

Attention!

note

Caution!

note

!DANGER!

note

Error

note

Hint

note

Important

note

Note

note

Tip

note

Warning

note


Catégorie Wiki

AdminDocs: Aide/Rédaction des documentations/Syntaxe Rest (last edited 30/07/2015 16:54:45 by NicolasJoubert1)