You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

5.5 KiB

INSTALLATION de PHPDocumentor

Dépendences du serveur :

php5-intl graphviz

Optionnellement (pour anciens templates xsl) : php5-xsl

Installation :

svn co svn://zone.spip.org/spip-zone/_galaxie_/code.spip.net/autodoc/trunk autodoc && cd autodoc
curl -sS https://getcomposer.org/installer | php
php composer.phar install
cd ..

En fonction de l'usage et du contenu de phpdoc.xml, il faudra créer un/des répertoires avec accès en écriture.

  • Avec l'application autodoc/bin/autodoc_helper.php :

    mkdir work

  • Avec l'executable autodoc/bin/autodoc.php (et en fonction du phpdoc.xml) :

    mkdir output && mkdir log

Mises à jour :

cd autodoc && svn up
php composer.phar self-update
php composer.phar update
cd ..

Notes sur les mises à jour:

J'ai aperçu que phpDocumentor copie les fichiers du template utilisé
dans son propre répertoire de templates. Il arrive que de vieux fichiers
trainent. Il faut donc supprimer `autodoc/vendor/phpdocumentor/templates/zora`
qui se recréera.

USAGE

Il y a deux exécutables disponibles.

  • L'un autodoc.php est l'équivalent de l'exécutable de phpdocumentor mais charge en plus le plugins SPIP pour phpdocumentor.

  • L'autre autodoc_helper.php est une application simplifiant l'utilisation en préconfigurant les commandes à transmettre à l'exécutable. Elle gère également le téléchargement des sources PHP à documenter.

Exécutable autodoc.php

Appel :

php autodoc/bin/autodoc.php

Le fonctionnement est exactement le même que le script phpdoc.php http://www.phpdoc.org/docs/latest/for-users/basic-usage.html

L'exécutable sans paramètre affiche la liste des actions et peut afficher, pour chaque action ses arguments et options possibles.

Appeler le template zora

Par commande :

php autodoc/bin/autodoc.php --template=autodoc/templates/zora

Par configuration :

php autodoc/bin/autodoc.php -c phpdoc.xml

Dans le fichier de configuration :

<phpdocumentor>
	[...]
	<transformations>
		<template name="autodoc/templates/zora">
		<!-- template name="responsive-twig"/ -->
		<!-- template name="clean"/ -->
	</transformations>
</phpdocumentor>

Autres options de configuration

Dans le fichier phpdoc.xml il est possible de définir les options suivantes qui agissent uniquement avec le template Zora :

<options>
	<site     value="http://code.spip.net/" />
	<chemin   value="autodoc/" />
	<proposer value="oui" />
	<titre        value="Documentation du code de SPIP." />
	<introduction value="Documentation du code PHP de SPIP." />
	<presentation value="Cette documentation est extraite du code source PHP de la version en développement de SPIP." />
</options>
  • site : si présent, le lien clicable du logo et du titre dans l'entête des pages renvoie vers cette URL. sinon, par défaut, cela renvoie vers le sommaire de la documentation automatique générée.
  • chemin : sert uniquement pour le .htaccess généré dans le cadre d'un site spip avec l'option site déclarée. Permet de rediriger @fonction sur l'url de la fonction
  • proposer : si présent, des boutons «proposer une amélioration» sont ajoutés sous certaines descriptions d'éléments. Ces liens pointent sur l'URL donnée par le paramètre site, sous entendant que c'est un site SPIP ayant activé le plugin Zora Docblock (préfixe zoradocblock), qui permet de gérer ces demandes d'amélioration.
  • titre : si présent, définit le titre affiché dans l'entête de page par ce texte.
  • description : si présent, ajoute cette information sur le sommaire de la documentation automatique générée.
  • presentation : si présent, ajoute cette information sur le sommaire de la documentation automatique générée.

Exécutable autodoc_helper.php

Appel :

php autodoc/bin/autodoc_helper.php

L'exécutable sans paramètre affiche la liste des actions et peut afficher, pour chaque action ses arguments et options possibles.

Quelques commandes et exemples

from:directory

Générer la documentation depuis un répertoire quelconque. Par défaut, la sortie est enregistrée dans le répertoire work/output/default

php autodoc/bin/autodoc_helper.php from:directory /home/marcimat/www/spip-dev

Forcer un préfixe de sortie ici dans work/output/spip-dev :

php autodoc/bin/autodoc_helper.php from:directory /home/marcimat/www/spip-dev --prefixe=spip-dev

from:svn

Générer la documentation depuis une source SVN quelconque.

php autodoc/bin/autodoc_helper.php from:svn svn://trac.rezo.net/spip/spip

from:spip

Générer la documentation depuis le svn du core

php autodoc/bin/autodoc_helper.php from:spip spip
php autodoc/bin/autodoc_helper.php from:spip branches/spip-3.0

from:zone

Générer la documentation depuis le svn de la zone

php autodoc/bin/autodoc_helper.php from:zone _plugins_/fabrique/trunk

from:plugin

Générer la documentation depuis le svn plugins de la zone

php autodoc/bin/autodoc_helper.php from:plugin fabrique/trunk

from:file

Générer des documentations dont les sources sont indiquées dans un fichier.

Par défaut, utilise le fichier svn de la zone.

php autodoc/bin/autodoc_helper.php from:file
php autodoc/bin/autodoc_helper.php from:file autodoc.txt
php autodoc/bin/autodoc_helper.php from:file svn://zone.spip.org/spip-zone/autodoc.txt