source: spip-zone/_galaxie_/code.spip.net/autodoc/trunk/installation.md @ 104202

Last change on this file since 104202 was 104202, checked in by marcimat@…, 3 years ago

Update des urls

File size: 6.3 KB
Line 
1INSTALLATION de PHPDocumentor
2=============================
3
4Dépendences du serveur :
5------------------------
6
7        php5-intl graphviz
8
9        Optionnellement (pour anciens templates xsl) : php5-xsl
10
11
12Installation :
13--------------
14
15        svn co svn://zone.spip.org/spip-zone/_galaxie_/code.spip.net/autodoc/trunk autodoc && cd autodoc
16        curl -sS https://getcomposer.org/installer | php
17        php composer.phar install
18        cd ..
19
20En fonction de l'usage et du contenu de phpdoc.xml, il faudra créer un/des répertoires avec accès en écriture.
21
22* Avec l'application `autodoc/bin/autodoc_helper` :
23
24        mkdir work
25
26* Avec l'executable `autodoc/bin/autodoc` (et en fonction du phpdoc.xml) :
27
28        mkdir output && mkdir log
29
30
31Mises à jour :
32--------------
33
34        cd autodoc && svn up
35        php composer.phar self-update
36        php composer.phar update
37        cd ..
38
39Notes sur les mises à jour:
40---------------------------
41
42        J'ai aperçu que phpDocumentor copie les fichiers du template utilisé
43        dans son propre répertoire de templates. Il arrive que de vieux fichiers
44        trainent. Il faut donc supprimer `autodoc/vendor/phpdocumentor/templates/zora`
45        qui se recréera.
46
47
48USAGE
49=====
50
51Il y a deux exécutables disponibles.
52
53* L'un `autodoc` est l'équivalent de l'exécutable de phpdocumentor
54  mais charge en plus le plugins SPIP pour phpdocumentor.
55
56* L'autre `autodoc_helper` est une application simplifiant l'utilisation
57  en préconfigurant les commandes à transmettre à l'exécutable.
58  Elle gère également le téléchargement des sources PHP à documenter.
59
60
61Exécutable autodoc.php
62----------------------
63
64Appel :
65
66        autodoc/bin/autodoc
67
68Le fonctionnement est exactement le même que le script `phpdoc`
69http://www.phpdoc.org/docs/latest/for-users/basic-usage.html
70
71L'exécutable sans paramètre affiche la liste des actions et peut afficher,
72pour chaque action ses arguments et options possibles.
73
74
75
76### Appeler le template `zora`
77
78
79Par commande :
80
81        autodoc/bin/autodoc --template=autodoc/templates/zora
82
83Par configuration :
84
85        autodoc/bin/autodoc -c phpdoc.xml
86
87Dans le fichier de configuration :
88
89        <phpdocumentor>
90                [...]
91                <transformations>
92                        <template name="autodoc/templates/zora">
93                        <!-- template name="responsive-twig"/ -->
94                        <!-- template name="clean"/ -->
95                </transformations>
96        </phpdocumentor>
97
98
99
100### Autres options de configuration
101
102
103Dans le fichier `phpdoc.xml` il est possible de définir les options suivantes
104qui agissent uniquement avec le template Zora :
105
106        <options>
107                <site     value="https://code.spip.net/" />
108                <chemin   value="autodoc/" />
109                <proposer value="oui" />
110                <titre        value="Documentation du code de SPIP." />
111                <introduction value="Documentation du code PHP de SPIP." />
112                <presentation value="Cette documentation est extraite du code source PHP de la version en développement de SPIP." />
113                <titre_onglets value="Autodoc" />
114                <topnav value="https://boussole.spip.net/?page=spipnav.js&amp;lang=fr" />
115        </options>
116
117- site :
118      si présent, le lien clicable du logo et du titre dans l'entête des pages renvoie vers cette URL.
119      sinon, par défaut, cela renvoie vers le sommaire de la documentation automatique générée.
120- chemin :
121      sert uniquement pour le .htaccess généré dans le cadre d'un site spip avec l'option site déclarée.
122      Permet de rediriger @fonction sur l'url de la fonction
123- proposer :
124      si présent, des boutons «proposer une amélioration» sont ajoutés sous certaines descriptions
125      d'éléments. Ces liens pointent sur l'URL donnée par le paramètre site, sous entendant que c'est
126      un site SPIP ayant activé le plugin Zora Docblock (préfixe zoradocblock), qui permet de gérer
127      ces demandes d'amélioration.
128- titre :
129      si présent, définit le titre affiché dans l'entête de page par ce texte.
130- description :
131      si présent, ajoute cette information sur le sommaire de la documentation automatique générée.
132- presentation :
133      si présent, ajoute cette information sur le sommaire de la documentation automatique générée.
134- titre_onglets :
135      si présent, utilise ce titre dans la barre de navigation
136- topnav :
137      Ajoute le contenu de topnav transmis par le script javascript retourné par l'url indiquée.
138      Le script JS retourné ajoute le HTML de la topnav, sa CSS, ainsi qu'une classe
139      HTML avec_boussole_topnav sur la balise <html>.
140
141
142
143Exécutable autodoc_helper.php
144-----------------------------
145
146Appel :
147
148        autodoc/bin/autodoc_helper
149
150L'exécutable sans paramètre affiche la liste des actions et peut afficher,
151pour chaque action ses arguments et options possibles.
152
153
154### Quelques commandes et exemples
155
156
157#### from:directory
158
159Générer la documentation depuis un répertoire quelconque.
160Par défaut, la sortie est enregistrée dans le répertoire `work/output/default`
161
162        autodoc/bin/autodoc_helper from:directory /home/marcimat/www/spip-dev
163
164Forcer un préfixe de sortie ici dans `work/output/spip-dev` :
165
166        autodoc/bin/autodoc_helper from:directory /home/marcimat/www/spip-dev --prefixe=spip-dev
167
168
169#### from:svn
170
171Générer la documentation depuis une source SVN quelconque.
172
173        utodoc/bin/autodoc_helper from:svn svn://trac.rezo.net/spip/spip
174
175
176#### from:spip
177
178Générer la documentation depuis le svn du core
179
180        autodoc/bin/autodoc_helper from:spip spip
181        autodoc/bin/autodoc_helper from:spip branches/spip-3.0
182
183
184#### from:zone
185
186Générer la documentation depuis le svn de la zone
187
188        autodoc/bin/autodoc_helper from:zone _plugins_/fabrique/trunk
189
190
191#### from:plugin
192
193Générer la documentation depuis le svn _plugins_ de la zone
194
195        autodoc/bin/autodoc_helper from:plugin fabrique/trunk
196
197
198#### from:file
199
200Générer des documentations dont les sources sont indiquées dans un fichier.
201
202Par défaut, utilise le fichier svn de la zone.
203
204        autodoc/bin/autodoc_helper from:file
205        autodoc/bin/autodoc_helper from:file autodoc.txt
206        autodoc/bin/autodoc_helper from:file svn://zone.spip.org/spip-zone/autodoc.txt
207
208Les documentations sont générées chacunes dans leur répertoire nommée par le préfixe du plugin
209et un sommaire est généré dans le répertoire de sortie (work/output par défaut) et les plugins
210générés sont dans work/output/$prefixe.
211
212Si le plugin n'a pas eu de commit depuis la dernière génération, la documentation
213n'est pas recrée.
214
215On peut forcer :
216
217- le répertoire de sortie : `--sorties=chemin`
218- le plugin généré (via son préfixe) : `--prefixe=saisies`
219- ou forcer la génération de la documentation, même si ce n'est pas nécessaire : `--force`
Note: See TracBrowser for help on using the repository browser.