Source

tacot / docs / fr / index.txt

Full commit
=====
Tacot
=====

Générer simplement des sites statiques.

But et fonctionnalités
======================

Ce projet est né de la demande suivante sur la mailing-list Python French : 
`« Un générateur de site statique mais plus "bas niveau" que blogofile, pelican, sphinx ? » <http://thread.gmane.org/gmane.comp.python.french/6696>`_.

*Tacot* permet de générer très simplement des sites statiques (génération de fichiers *.html*)
à partir de fichiers templates écrits en `Mako <http://www.makotemplates.org/>`_.

Quelle est l'utilité par rapport à l'écriture de simples fichiers *.html* ?

  Avec *Tacot* vous pouvez mettre en place facilement des parties communes dans vos pages 
  (exemples: *entête*, *bas de page*, *navigation*) sans avoir à dupliquer ces sections
  dans tous les fichiers du site.


Il existe de nombreux générateurs de site statique en Python, comme `Sphinx <http://sphinx.pocoo.org/>`_, `pelican <http://pypi.python.org/pypi/pelican/>`_... pourquoi réinventer la roue ?

  *Tacot* n'est pas une réinvention de la roue… lorsque j'ai effectué ma recherche, je n'ai rien trouvé qui
  corresponde à mon besoin basique. Je n'ai pas besoin de parsing de ReStructredText, je ne souhaite pas
  gérer des billets de blog, je ne souhaite pas réaliser une documentation, je ne souhaite pas utiliser
  un système de thème…

  Je veux simplement convertir de simples fichiers templates en html… et ça je n'ai pas trouvé.



Installation
============

::

    $ pip install tacot


Exemple rapide
==============

Téléchargez l'archive `demo1.tar.gz <_static/demo1.tar.gz>`_ dans un dossier ``demo1``.

::

    $ mkdir demos; cd demos
    $ curl -o demo1.tar.gz http://packages.python.org/tacot/en/_static/demo1.tar.gz
    $ tar xfz demo1.tar.gz
    $ cd demo1

Voici le contenu de l'archive :

::

    $ tree
    .
    ├── earth.html
    ├── includes
    │   ├── layout.html
    │   └── navigation.html
    ├── index.html
    ├── jupiter.html
    ├── mars.html
    ├── mercury.html
    ├── neptune.html
    ├── pluto.html
    ├── saturn.html
    ├── styles.css
    ├── uranus.html
    └── venus.html

Génération du site :

::

    $ tacot
    Please wait, tacot process 11 files :

    jupiter.html
    pluto.html
    neptune.html
    styles.css
    index.html
    saturn.html
    uranus.html
    earth.html
    mars.html
    venus.html
    mercury.html


Après cela, le site généré se trouve dans le dossier ``_build`` :

::

    $ ls _build/ -1
    earth.html
    index.html
    jupiter.html
    mars.html
    mercury.html
    neptune.html
    pluto.html
    saturn.html
    styles.css
    uranus.html
    venus.html

Vous pouvez le consulter en faisant pointer votre navigateur web vers ce dossier :

::

    $ firefox _build


Utilisation
===========

::

    $ tacot --help
    usage: tacot [-h] [-o OUTPUT] [-m MANIFEST] [path]

    A tool to generate a static web site, with Mako templates.

    positional arguments:
      path                  Path where to find the content files

    optional arguments:
      -h, --help            show this help message and exit
      -o OUTPUT, --output OUTPUT
                            Where to output the generated files. If not specified,
                            a directory will be created, named "_build" in the
                            current path (_build by default).
      -m MANIFEST, --manifest MANIFEST
                            Manifest config file (.manifest by default)
      -r, --autoreload      Relaunch tacot each time a modification occurs on the
                            content files



Par défaut, *Tacot* traite les fichiers du dossier courant et place de résultat dans le dossier
``_build`` du dossier courant.

Vous pouvez changer ce comportement, par exemple :

::

    $ tacot -o /var/www/demo/ /tmp/demo1

Ici, les templates sont dans ``/tmp/demo1`` et le site est généré dans ``/var/www/demo/``.

Fichier ``.manifest``
---------------------

Le fichier ``.manifest`` permet de définir la liste des fichiers à traiter.
Par défaut il contient la configuration suivante :

::

    global-include *
    prune _build/
    prune includes/

Les dossiers ``_build`` et ``includes`` sont ignorés.

La syntaxe du fichier ``.manifest`` est identique à celle du fichier
``MANIFEST.in`` des packages Python : `documentation « The MANIFEST.in template » <http://docs.python.org/distutils/sourcedist.html#the-manifest-in-template>`_

Option ``--autoreload``
-----------------------

L'option ``--autoreload`` permet de relancer la génération du site automatiquement
à chaque fois qu'un changement a lieu dans l'arborescence des fichiers sources :

::

    $ tacot --autoreload

``CTRL-C`` permet d'arrêter le script.


FAQ
===

Avez vous des exemples d'usage de *Tacot* ?
-------------------------------------------

Pour le moment il n'existe aucun exemple en ligne de site réalisé avec *Tacot*.
Par contre, je compte utiliser *Tacot* pour :

* réaliser des *mockup* d'application ou de site web
* réaliser de petits sites de contenu


Comment héberger / publier le site généré ?
-------------------------------------------

Pour héberger un site généré par *Tacot*, rien de plus simple, il suffit de 
transférer le contenu du dossier généré (par défaut nommé ``_build``) et
de le déposer dans un dossier d'un simple serveur web.

Ici, pas de base de données, pas de langage php, python,… le serveur web
doit uniquement gérer des simples fichiers statiques.


Comment ajouter le support de commentaire ?
-------------------------------------------

Il est possible de mettre en place un système de commentaire en
utilisant des services en ligne comme `Disqus <http://disqus.com/>`_.


Comment ajouter un moteur de recherche ?
----------------------------------------

`Sphinx <http://sphinx.pocoo.org/>`_ intègre un moteur de recheche basé uniquement
sur le langage Javascript coté client. Je pense qu'il doit être possible de mettre
en place un système plus ou moins identique avec un site généré par *Tacot*.

Pour le moment je n'ai pas plus étudié le sujet.


Contributions
=============

Vous pouvez récupérer le code source du projet via cette commande 
(c'est un dépôt Mercurial) :

::

    $ hg clone http://bitbucket.org/harobed/tacot

Vous pouvez forker le projet, indiquer les problèmes, proposer des patchs via
le compte Bitbucket du projet `Tacot <https://bitbucket.org/harobed/tacot>`_.