Générer la documentation Symfony2

Symfony2 bouge encore relativement beaucoup, et c’est donc aussi le cas de sa documentation. Si comme moi vous aimez toujours utiliser la dernière version de Symfony encore en développement, et que vous aimeriez disposer de la documentation en local et toujours à jour, voici comment procéder.

Récupérer la documentation sur git

La documentation officielle de Symfony2 est bien sur hébergée sur Git. Rendez-vous sur le dépôt Git officiel et clonez la documentation en local.

git clone git://github.com/symfony/symfony-docs.git

Installer Sphinx

Tout d’abord la documentation Symfony2 est générée grâce à Sphinx, un projet écrit en Python. Il serait donc de bon aloi de l’installer ;-)

Si comme tout gens bien vous utilisez ArchLinux, il vous suffit d’un petit

sudo pacman -S python-sphinx

Pour les autres utilisez easy_install directement :

easy_install -U Sphinx

SI vous n’avez pas easy_install (hey les gens, faut vraiment vous mettre au Python !), c’est par ici.

Créez un Makefile

Pour l’instant, le repo Git officiel ne fournit pas de Makefile pour générer la documentation. Il va donc falloir en créer un. Pour ce faire utilisez la commande suivante dans votre répertoire symfony-docs :

sphinx-quickstart

Cette commande va vous poser tout plein de questions, acceptez toujours les choix par défaut (appuyez sur entrée pour ce faire). Vous aurez juste trois choses à saisir, le nom du projet (mettez Symfony2), le nom de l’auteur (Fabien Potencier serait fair play ;-) ) et la version (est-ce un piège ?).
Lorsque cette question va arriver > Name of your master document (without suffix) mettez n’importe quoi d’autre que index, on s’en fiche un peu, mais si vous mettez index il va pas être content le mÔssieur.

Installez l’extension configuration

Fabien a du créer une extension pour gérer plusieurs formats (YAML/XML/PHP dans notre cas) pour les fichiers de configuration. Pour l’installer, créez un répertoire _exts dans votre répertoire symfony-docs et placez-y le fichier se trouvant sur le repo Git sphinx-php de Fabien.

Éditez le fichier conf.py qui se trouve dans symfony-docs, et ajoutez-y cette ligne en haut après la ligne d’import :

sys.path.append(os.path.abspath('_exts'))

Trouvez ensuite la ligne des extensions et rajoutez-y celle que l’on a téléchargée plus haut :

extensions = ['configurationblock']

Vous être prêt à générer votre première documentation Symfony2.

make html

Et voilà ! Le fichier index.html généré se trouve dans _build/html/index.html

Amusez-vous bien, et n’hésitez pas à contribuer dès que vous le pouvez.

Tags: documentation, symfony2

A propos de l'auteur

Vince

Développeur depuis une dizaine d'années maintenant il se tourne de plus en plus vers Ruby et les langages fonctionnels comme Scala. Après plusieurs années en tant que salarié, une reprise d'études, une thèse, et un passage chez knpLabs, il a récemment rejoint l'équipe de Jirafe. Vous pouvez le trouver sur irc, twitter, sur Github ou un peu partout sous le pseudo vjousse. Il tient aussi un blog sur le développement personnel.

Sur le même sujet

• Python tips & tricks
• Un PHP5 toutes options pour votre Léopard
• Uploadez en Symfony
• Effectuer un pré et/ou post traitement dans vos actions Symfony
• atoum tire la couverture

Vous avez aimé ce billet? Faites le savoir!

• 
• 
• 
• 
• 
•