.----------------------------.
.--=]   Introduction à Pelican   [=------------------------------------------.
:   '----------------------------'                                           :
:                     .-----------------------------.                        :
'--------------------=]     Sat 22 January 2011     [=-----------------------'
                      '-----------------------------'

Ca faisait pas mal de temps que je cherchais un outil pour diffuser mes projets.
Comme beaucoup je me suis naturellement tourné vers les outils largement répendus
du type wordpress, dotclear, spip...  Bien qu'ils proposent une interface assez
simple (et encore) et une ribambelle de pluggins, vient un moment où ca fait
véritablement usine à gaz.


Du coup, j'ai commencé à développer mon propre outil. De fil en aiguille, j'ai
vu qu'il exister déjà des outils similaire à ce que je voulais faire : miniLOL,
blogofile, et finalement Pelican. C'est vers celui-ci que je me suis tourné.


---=[ 0x00 ]=--- ---=[ Pelican, What's that ? ]=---


Pelican est un générateur de blog statique (html) écrit en python, et même plus.
On rédige nos articles, on compile le tout et on a un site entier prèt à être
uploader sur le serveur. Pour un site ayant beaucoup d'articles, c'est un peu
chiant de devoir générer à la moindre modification son site, mais pour un
petit projet c'est parfait. Ca tombe bien !


---=[ 0x01 ]=--- ---=[ Pourquoi mon choix s'est porté sur Pelican ? ]=---


Tout simplement parce que c'est exactement ce que je cherchais :
- Ecrit en Python (moins de 1000 lignes de code)
- Edition des articles dans mon editeur de texte favori (vim, emacs, gedit...)
en utilisant Markdown ou reStructuredText pour la mise en page.
- Pas de langage serveur : sécurité renforcé, moins de travail pour le serveur
- Rapidité de chargement
- Sauvegarde des articles simplifiées
- Utilisation de Template (avec jinja2)
- Coloration syntaxique avec Pygments
- Génération "intuitive" du site : Pas besoin de tout regénéré à chaque fois
- Possibilité d'ajouter de nouveau lecteurs et générateurs : par exemple en texte
brut ou HTML
- etc... etc...


Trève de blah blah, Let's Go !


---=[ 0x02 ]=--- ---=[ Générer un site ]=---


Après avoir installer Pelican, on va commencer, pour decouvrir Pelican, par
générer la documentation. Elle est fournit dans l'archive dans le dossier docs :


$ pelican docs/



Le site est généré dans le dossier /output, avec le thème notmyidea.Si on veut
changer de thème, on utilise l'option -t dans la ligne de commande suivie du nom
du thème qu'on veut utiliser :


$ pelican docs/ -t brownstone



Pelican est fourni avec 4 thèmes : notmyidea, brownstone, simple et martyalchin.
On verra un peu plus loin les bases de la création d'un thème.


---=[ 0x03 ]=--- ---=[ Fichier de configuration ]=---


On peut configurer Pelican avec un fichier de configuration. On peut par exemple
spécifier le thème à utiliser et tout un tas d'autres options. Il suffit de le
spécifier dans la ligne de commande avec l'option -s :


$ pelican -s /cheminDeMonFichierConf/conf.py



Les paramètres sont stockés dans un fichier python qui sera utilisé comme module
python.  Ces paramètres doivent impérativement être en majuscule, sinon ils ne
seront pas traités.









Paramètre
Action





AUTHOR
L'auteur par défaut



CATEGORY_FEED
Flux par catégories en Atom
Par défaut est feeds/%s.atom.xml, où %s est le nom de la
catégorie.



CATEGORY_FEED_RSS
Flux par catégories en rss.
Par défaut None (no rss)



CSS_FILE
Spécifié le fichier CSS que vous voulez charger, si ce
n'est pas celui par défault ('main.css')



DEFAULT_CATEGORY
La catégorie par défault qu vous voulez mettre.  Si vous
ne spécifié pas cette option misc. sera la catégorie par
défaut.



DEFAULT_LANG
La langue du site. Par défaut, english : 'en'



DISPLAY_PAGES_ON_MENU
Afficher ou pas les pages dans le menu du modèle.
Les modèles peuvent suivre ou pas ces paramètres.



FALLBACK_ON_FS_DATE
Si True, le pélican utilisera le système de fichier
(mtime)  pour obtenir les infos sur la date s'il ne
peut obtenir des informations à partir des métadonnées



FEED
Flux global du site en atom
Par défaut feeds/all.atom.xml



FEED_RSS
Flux global du site en rss
Par défault None (no rss)



JINJA_EXTENSIONS
Une liste de toutes les extensions Jinja2 vous souhaitez
utiliser. Par défaut la liste est vide.



KEEP_OUTPUT_DIRECTORY
Par défaut le répertoire de sortie est supprimé et le
site est intégralement généré. En spécifiant cette option,
pelican garde ce qui a déjà été généré et génére juste
les dernières modifications.



MARKUP
Une liste des langages de balisage disponibles que vous
souhaitez utiliser.
Pour l'instant, seules les valeurs rst (reStructuredText)
et md (MarkDown) sont disponibles



OUTPUT_PATH
Où stocke-t-on les fichiers générés.
Par defaut dans "output"



PATH
Chemin pour les fichiers en entrée



PDF_PROCESSOR
Mettez la valeur True si vous voulez avoir des versions
PDF de vos documents. Vous aurez besoin d'installer
rst2pdf.



REVERSE_ARCHIVE_ORDER
Renverse l'ordre des archives. (True pour un ordre
décroissant: la dernière créée est en premier)



SITEURL
URL de votre site.



SITENAME
Nom de votre site,



STATIC_PATHS
Le path static que vous voulez avoir sur le path de
sortie. Par défaut, pelican copie le dossier "images"
dans le dossier de sortie.



STATIC_THEME_PATHS
Path du thème static que vous souhaitez copier.
Par défaut static, mais si votre thème a d'autres path,
vous pouvez les mettre ici.



THEME
Theme à utiliser pour générer la sortie.Doit être le
chemin complet du dossier de votre theme, ou choisissez
un theme dans la list par défaut.



TRANSLATION_FEED
Flux par langue. Par défaut est feeds/all-%s.atom.xml
avec %s est le nom de la langue.






Volà pour les paramètres du site. On peut aussi ajouter d'autres paramètres. Par
exemple, si vous avez un compte Git, un twitter, ou si vous vous êtes inscrit sur
Disqus pour gérer des commentaires sur votre site, vous pouvez configurer tout
ça dans votre fichier de configuration.









Paramètre
Action





DISQUS_SITENAME
Pelican peut traiter les commentaires avec Disqus,
préciser le nom du site que vous avez rempli sur Disqus



GITHUB_URL
URL de votre github (si vous en avez un), cela aura pour
effet de créer un ruban : "Fork me on github"



GOOGLE_ANALYTICS
'UA-XXXX-YYYY' pour activer google analytic.



LINKS
Une liste de tuples (Title, Url) pour afficher des liens



SOCIAL
Une liste de tuples (Title, Url) qui apparaîtront dans
la section "social"






Ci-dessous le fichier conf.py que j'utilise pour générer ce site :
---=[BEGIN]=---=[ CUT HERE ]=---


#-*- coding: utf-8 -*-

# ---=[ General configuration site ]=-----
AUTHOR = u'Shebang'
SITENAME = u"Shebang Labs"
SITEURL = 'http://shebang.tuxfamily.org'
DEFAULT_LANG = 'fr'
#PATH

# ---=[ Feed configuration ]=-----
FEED= 'feeds/all.atom.xml'
#FEED_RSS = 'feeds/all.rss.xml'
#CATEGORY_FEED= 'feeds/%s.atom.xml'
#CATEGORY_FEED_RSS = 'feeds/%s.rss.xml'
#TAG_FEED = 'feeds/%s.atom.xml'
#TAG_FEED_RSS = 'feeds/%s.rss.xml'

# ---=[ Output configuration ]=-----
OUTPUT_PATH = 'shoutput/'
#CSS_FILE
DEFAULT_CATEGORY = u'Home'
REVERSE_ARCHIVE_ORDER = True
FALLBACK_ON_FS_DATE = True
KEEP_OUTPUT_DIRECTORY = True
MARKUP = 'rst'
DISPLAY_PAGES_ON_MENU = True
PDF_PROCESSOR = False
#JINJA_EXTENSIONS

# ---=[ Theme configuration ]=-----
#THEME
#STATIC_PATHS
#STATIC_THEME_PATHS

# ---=[ Other configuration ]=-----
#GITHUB_URL = 'http://github.com/ametaireau/'
DISQUS_SITENAME = "shebanglabs"

#LINKS = (('Biologeek', 'http://biologeek.org'),
#            ('Filyb', "http://filyb.info/"),
#            ('Libert-fr', "http://www.libert-fr.com"),
#            ('N1k0', "http://prendreuncafe.com/blog/"),
#            (u'Tarek Ziadé', "http://ziade.org/blog"),
#            ('Zubin Mithra', "http://zubin71.wordpress.com/"),)

#SOCIAL = (('twitter', 'http://twitter.com/ametaireau'),
#          ('lastfm', 'http://lastfm.com/user/akounet'),
#          ('github', 'http://github.com/ametaireau'),)



---=[END]=---=[ CUT HERE ]=---


Voilà pour le fichier de configuration. Si vous voulez utiliser un fichier de
configuration, je vous conseille de ne pas modififier le setting.py mais de créer
un fichier à part que vous appelerai en ligne de commande. Sachez aussi que le
fichier de config n'est pas obligatoire.


On va maintenant approfondir certains de ces paramètres.


---=[ 0x04 ]=--- ---=[ keep-output-directory ]=---


Pelican est un générateur de site. L'inconvénient majeur est que par défaut
pelican regénére l'integralité des fichiers pour la moindre modification.
Imaginez que vous ayez 1000 articles, ca peut prendre pas mal de temps. Fort
heureusement, pelican à une astuce pour éviter de compiler l'ensemble du site,
mais juste les modifications apporter : le paramètre KEEP_OUTPUT_DIRECTORY


En ligne de commande, il faut utiliser l'option -k :


$ pelican -k
ou
$ pelican --keep-output-directory



On peut aussi ajouter cette option dans le fichier de configuration :


KEEP_OUTPUT_DIRECTORY = True



---=[ 0x05 ]=--- ---=[ Flux de syndication ]=---


Pelican permet de gérer plusiseurs flux. Encore faut-il lui dire. Cette fois
encore, c'est dans le fichier de configuration que ça se passe (d'où l'intérêt
d'en créer un :). Il suffit juste de rajouter cette ligne pour un flux Atom :


FEED = 'feeds/all.atom.xml'



Si c'est un flux rss que vous souhaitez, c'est le paramètre FEED_RSS qu'il faudra
rajouter. Vous pouvez aussi gérer vos flux par catégorie ou par tags. Voici tous
les flux, ajoutez juste un dièse ("#") devant pour les désactiver.


FEED = 'feeds/all.atom.xml'
FEED_RSS = 'feeds/all.rss.xml'
CATEGORY_FEED = 'feeds/%s.atom.xml'
CATEGORY_FEED_RSS = 'feeds/%s.rss.xml'
TAG_FEED = 'feeds/%s.atom.xml'
TAG_FEED_RSS = 'feeds/%s.rss.xml'



---=[ 0x06 ]=--- ---=[ Coloration syntaxique ]=---


Pour utiliser pygments, il suffit de faire un fichier css qu'on place dans le
dossier static/css/ du thème. Ensuite pour l'utiliser, avec reStructuredText par
exemple, il faut ajouter ceci juste avant le bout code :


.. code-block:: python  // pour une coloration avec python
    Mon code python indenté
.. code-block:: console // pour les commandes de la console
    ma ligne de commande indenté



---=[ 0x07 ]=--- ---=[ Créer son thème ]=---


Pelican utilise le moteur de modéles jinja2 pour générer sa sortie HTML.


Un thème doit avoir la structure suivante :


├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html    // pour afficher les archives
    ├── article.html     // Traitement de chaque article
    ├── categories.html  // énumérer toutes les catégories
    ├── category.html    // traitement pour chaque catégorie
    ├── index.html       // l'index : pour lister tous les articles
    ├── page.html        // Traitement pour chaque page
    ├── tag.html         // Traitement pour chaque tags
    └── tags.html        // énumer tous les tags ou pour faire un nuage de tags



static contient tout le contenu statique images, css, etc...
templates contient tous les modèles qui seront utilisés pour générer le
contenu. Ici seul les modèles obligatoires sont présentés dans la structure de
base. Vous pouvez en ajouter d'autres.


Modèles et variables


Tous les modèles recevront les variables définies dans votre fichier de
paramètres, s'ils sont en majuscules. Vous pouvez y accéder directement.


    

  • Les variables communes
    • 



Toutes ces variables sont utilisés dans tous les modèles.









Variables
Action





articles
C'est la liste des articles, classé par date décroissant,
tous les éléments sont des objets article, vous pouvez
donc accéder à leurs propriétés (par exemple au titre,
résumé, auteur, etc



dates
La même liste de l'article, mais classés par date
ascendante



tags
Un dictonnaire contenant chacun tags, et la liste des
articles associés.



category
Un dictionnaire contenant chaque catégorie, et la liste
des articles associés.



pages
La liste des pages






    

  • category.html
    • 



Ce modèle sera traitée pour chacune des catégories existantes, et sera généré
dans output/category/category_name.html.









Variable
Action





articles
Les articles de cette catégorie



category
Le nom de la catégorie en cours






    

  • article.html
    • 



Ce modèle sera traitée pour chaque article. les fichiers .html seront générés
dans output/article_name.html. Voici les variables spécifiques qu'il doit avoir.









Variable
Action





article
L'objet article à afficher



category
Le nom de la catégorie de l'actuel article






    

  • tags.html
    • 



Ce modèle sera traitée pour chaque tags. Il permettra de créer des fichiers
.html dans  /output/tag/tag_name.html









Variable
Action





tag
Le nom du tag en cours



articles
Articles liés à ce tag






Nous verrosn dans un prochain article comment réaliser de son thème en détail.


---=[ 0x08 ]=--- ---=[ Le mot de la faim ]=---


Voilà s'en ai fini pour cette petite introduction à Pelican. En espérant que
cela vous ai donner envie d le tester et peut-être même de l'utiliser.
Quelques liens :


pelican : le site officiel
Github : le Github de pelican
freeculture : un blog réalisé avec pelican où il y a pas mal de docs, dont
certaines m'ont servies pour faire ce site et cette introduction.
jinja2 : Documentation de jinja2
Markdown Documentation de MarkDown
reStructuredText Documentation de reStructuredText
pygments : Coloration syntaxique


                                       ````-:-...```
                                    .--..-/+++oo+/-.-.`
                                  `-oo:/`..-::--:+o+oo-
                                .+o/:/-:-...::+/+ooyy+.
                              -+syooos+::-++o++:/+oo+.``
                            -syssyyyo+++////o/://oo+/-``
                         `/ososyyoooosydh+::/+///++/:-.`
                       -oo+oyhyyyhhyyyyyyyy:/++/+///+-`
                    `:ooosssydhhsossoso+++sy+o+++o++/.
                  .:++ossshhhhyyyossso+//oys+++oo+o+.
               `-++ooooyhyysoyyssssysooydyo+::/os+:.
             `:+ooossyhyyysooyssssso+/ohs/::/+:/+:`
           .:+ssssyhyssssosssso+::../sho+::/:/+/-
         -+oosyhdhsosoo/-...``    :syso:/++o++/`
      `-+ooshddhyso/-.`         .+yys+//osso:.
    `:++shddyo/:.``            ./o+o++++ys:`
 `.:o+oyyo:.                  ://+oooosho.
:oo+/::.`                    :o++ossyshy`
.-.                         `syssyhhhhdy`
                            .:/osyyhhyyyo:.`
                         ```.````-+yhhhhy++++///++/--.:-.--.`
                        .-....````.:shso+oosooosooo+oyso+//-..`
                       /:/:/-::.``..-+y+/oo/+shyo/oo/+o/++ooo/:..
                      :oss+:/:--..``-:+/++o::oyyh+osoos+ossos/:.```
                      /+//+oo::/......-::/+-::s+yys+ossyss+/++.``.`
                     `///osoo:/:-.`..`.:/o:.:+yosys+/soyyss+/-/..::-`
                     `++/oosy+o-.-`....-/o:+/+/oodyy+oy/+++h+:-/:..+-
                      -o+/oooso:./:-`:.-.:+/-/:s/myyy:++/yoy/-.`+/::.`
                      `ooos/ysy/:+//`..o:.+:/+-o/doos++:/h/+--/-:::-+-
                       -yoo/yoss+/o:`::/o--o/+:+:dy/o-:y+h+-`:s+:+//o:.
                        ++soyyyy/+o//+.so+o+os+/+hdo+`oh/+y/-o//:+-+/--
                         +syssosysohs--o::/-/+ss+odh/-yys:/s/oo::hsy++:
                         -o+so+hsyos+-.s+-+o/o-/y/hhh+sdyossoso:/h+s-o-
                          /o++oysyy+os:ho+o+/o.oh:dhhoodyy+/-hso.+y+:/-
                           :/o+++sd//hhoyh:/:/+hsoymdysy+dy+/hhys:+y-/-
                            -o++/ss+:+s+s:/:+:hs+dymmdmh/shyddh+s-:///-
                             :o++/o/yy/+-//+:/o-oymNNNmh:/odmyos//y/s/-
                              -/o/o:+y./:+/+s:-+h/mmNNmd-+ymNs++sss+y:-
                              `shh:ssoo/:++y+-/:o+mmmdmm+/ddmy+/+s+s++`
                               shdyoo+-.ohs//s/.+omdmhddo:yydy-oos-y++
                               /hhyhoy`/s++yss.-+hhhdhdhh:s/dh-:d+:/s`
                               `shhhhy:oohho/+.+ohsyhsdhh:s:yh:oh::/.
                                -hy+yhhohyo//::yhoossosyy::ooo+o/..`
                                 -s/ohh:o+s+/-osh+syo++yys-smddo/.
                                  hd+:ohhdNdyhy+sssso:/syyddmmmms`
                                  hs` .mmNmmydho+h/yds+syyNNNmdhy/
                                 .do  `dmmmh+yo+oyshhhyyshNmmhhhyo`
                                `omo  `ydmmdyo//+ss+ssoohyhyssyyho:
                              :osdmdso++hsddmo+h++doshyoyysyysssh:-
                              `:+sddmmo/y/oohoyhhy+yy+s-+shyss+-s:.
                                  .---.:+///s+++:s.o+:/`-ooy+o/`::
                                       `.-::o:-:.+`o-: ..//o-/.
                                         `..+.--`--:.   .:-. `
                                           ``    `:.     `
 
         .--------------------.
      --=[    Commentaires    ]=--
         '--------------------'