Impression
Un site web destiné à être publié doit être structuré par rapport à l'arborescence du disque. C'est à dire sous forme de fichiers répartis dans des répertoires.
Les fichiers peuvent être au format RST ou HTML. Ils seront automatiquement intégrés dans un template pour générer la page finale comprenant entête et menu de navigation.
Un fichier de configuration est utilisé pour définir le menu de chaque répertoires, il décrit les fichiers qui vont apparaître dans le menu de navigation éventuel.
La génération se fait soit à l'aide de l'interface web soit en ligne de commande.
Les fichiers RST doivent être de la forme nom_du_fichier.rst, ils seront transformés automatiquement (en l'écrasant) en page html de de la forme nom_du_fichier.html après passage par le template
Il est possible d'insérer et redimensionner des images grace à l'interface web.
Spécifiez une largeur ou une longueur maximale, l'échelle sera conservée.
Publy reconnait les formats de PIL : http://www.pythonware.com/library/pil/handbook/image-file-formats.htm
Pour changer de format, il suffit de spécifier une extension du nom de fichier (.jpg, .gif...) différente de celle d'origine. Par exemple image.jpg à partir d'un fichier image.bmp
Les documents RST sont automatiquement transformés en html, mais il est également possible d'ajouter ses propres pages html.
Dans chaque répertoire un fichier de configuration de la forme menu.yaml permet de générer le menu de navigation.
Il doit contenir des informations pour chaque entrée d'une manière structurée (yaml) à respecter scrupuleusement. Les espaces à gauche de chaque lignes sont significatifs:
label: nom du répertoire tel qu'il sera affiché
menu:
- nom_du_fichier1: label du fichier pour le menu
ou
- nom_du_fichier2:
label: label du fichier pour le menu
title: titre du fichier pour le plan_
url: url si cette entrée est un lien vers une autre destination
- ---- (4 tirets pour faire une rupture dans le menu
ou
- ----: label de la rupture
index: nom du document rst (sans extension) qui servira d'index
(et écrasera index.html)
ou "__plan__" pour le générer automatiquement à partir
de label et title des éléments du menu
Le premier fichier à s'ouvrir sera soit
Si aucun fichier index n'existe le plan est généré automatiquement, il reprend chaque entrée du menu et affiche un lien vers les fichiers. Il utilise le label et le titre éventuellement saisis dans le menu.
Il est également possible d'ajouter des données autres qu'en rst. Ces données seront accessibles dans le template sous la forme $data.get("nom_de_la_donnée")
En commençant le document par:
.. data nom_donnee: contenu de la donnée autre_nom: autre contenu ...
Les données sont au format yaml, il est donc possible d'indiquer toutes sortes de combinaisons...
Ensuite le reste du texte est en RST. Il n'est pas indispensable d'indiquer du texte.
Attention!
data n'est pas une directive il ne faut donc pas indiquer les :: à la fin, sous peine de ne pouvoir générer la page avec docutils tout seul.
Au niveau de chaque entrées du menu:
menu:
- premier:
label: label du menu
data:
nom_donnee: contenu de la donnée
autre_nom: autre contenu
etc.
Ou globalement pour le répertoire, toujours dans le fichier menu.yaml:
menu: - ... data: nom_donnee_globale: ... autre_nom: ...