6.3 KiB

Raw Blame History

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 :

mkdir work
Avec l'executable autodoc/bin/autodoc (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 est l'équivalent de l'exécutable de phpdocumentor mais charge en plus le plugins SPIP pour phpdocumentor.
L'autre autodoc_helper 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 :

autodoc/bin/autodoc

Le fonctionnement est exactement le même que le script phpdoc https://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 :

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

Par configuration :

autodoc/bin/autodoc -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="https://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." />
	<titre_onglets value="Autodoc" />
	<topnav value="https://boussole.spip.net/?page=spipnav.js&amp;lang=fr" />
</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.
titre_onglets : si présent, utilise ce titre dans la barre de navigation
topnav : Ajoute le contenu de topnav transmis par le script javascript retourné par l'url indiquée. Le script JS retourné ajoute le HTML de la topnav, sa CSS, ainsi qu'une classe HTML avec_boussole_topnav sur la balise <html>.

Exécutable autodoc_helper.php

Appel :

autodoc/bin/autodoc_helper

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

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

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

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

from:svn

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

utodoc/bin/autodoc_helper from:svn svn://trac.rezo.net/spip/spip

from:spip

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

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

from:zone

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

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

from:plugin

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

autodoc/bin/autodoc_helper 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.

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

Les documentations sont générées chacunes dans leur répertoire nommée par le préfixe du plugin et un sommaire est généré dans le répertoire de sortie (work/output par défaut) et les plugins générés sont dans work/output/$prefixe.

Si le plugin n'a pas eu de commit depuis la dernière génération, la documentation n'est pas recrée.

On peut forcer :

le répertoire de sortie : --sorties=chemin
le plugin généré (via son préfixe) : --prefixe=saisies
ou forcer la génération de la documentation, même si ce n'est pas nécessaire : --force

6.3 KiB Raw Blame History