Browse Source

Mise à jour vers PhpDocumentor v3

Une bonne partie de l’application Autodoc disparait pour plusieurs raisons :

- On cherche à simplifier la maintenance de cette doc en ne créant pas de thème personnalisé,
car effectivement, la syntaxe PHP évolue bien plus vite que le temps disponible
pour adapter les templates aux évolutions. On préfère user juste d’un peu de
cosmétique avec un peu de CSS. Le thème complet d’avant disparait.
- L’application est devenue un .phar et les surcharges sont improbables là où le code
d’origine ne l’a pas explicitement prévu. Je n’ai absolument pas l’énergie
de me replonger à gérer des passes de compilation comme avant pour retrouver
les balises ou pipelines dans le code (je ne sais même pas si c’est faisable sur cette version).
Cette partie disparait aussi.
- On bascule sur du PHP 8.0 minimum.

On s’appuie sur différentes librairies dont toujours symfony/console, mais aussi
symfony/filesystem et League/Pipeline.

On gère les téléchargements et mises à jour Git avec l’outil checkout
(qui est donc nécessaire). Le fichier phpDocumentor.phar est aussi nécessaire
dans le répertoire de travail, tout comme la création d’un répertoire `var`
écrivable.

Une décoration spécifique du thème par défaut (css, svg), est copiée
dans la config générée (var/config/templates), et est alors utilisée
par phpDocumentor (sur le même principe de surcharge que les squelettes SPIP)

Les commandes from:directory, from:git, from:plugin, from:spip sont adaptées.
La commande from:file (lecture d’un fichier archivelist.txt) reste à faire.
master
Matthieu Marcillaud 9 months ago
parent
commit
6c9d36c26e
  1. 156
      .gitattributes
  2. 2
      .gitignore
  3. 103
      README.md
  4. 18
      bin/autodoc
  5. 29
      bin/autodoc_helper
  6. 14
      composer.json
  7. 3415
      composer.lock
  8. 219
      installation.md
  9. 11
      old/FromFile.php
  10. 294
      old/GeneratorOld.php
  11. 5
      placeholders/index.html
  12. 56
      placeholders/phpdoc.xml
  13. 27
      src/Application.php
  14. 79
      src/Checkout.php
  15. 78
      src/Command/FromDirectory.php
  16. 96
      src/Command/FromGit.php
  17. 43
      src/Command/FromPlugin.php
  18. 60
      src/Command/FromSpip.php
  19. 43
      src/Command/FromZone.php
  20. 88
      src/Context.php
  21. 9
      src/Exception/AutodocException.php
  22. 9
      src/Exception/ContextException.php
  23. 28
      src/Generator.php
  24. 50
      src/Git.php
  25. 43
      src/Loader/AbstractLoader.php
  26. 34
      src/Loader/Collection.php
  27. 8
      src/Loader/LoaderInterface.php
  28. 106
      src/Package.php
  29. 35
      src/Stage/CheckStage.php
  30. 13
      src/Stage/GitSpipStage.php
  31. 69
      src/Stage/GitStage.php
  32. 87
      src/Stage/PackageStage.php
  33. 93
      src/Stage/PhpDocumentorConfigStage.php
  34. 27
      src/Stage/PhpDocumentorStage.php
  35. 11
      src/Stage/StageInterface.php
  36. 86
      src/autodoc/Application.php
  37. 45
      src/autodoc/Configuration.php
  38. 59
      src/autodoc/Configuration/Option.php
  39. 85
      src/autodoc/Configuration/Options.php
  40. 44
      src/autodoc/Helpers/Application.php
  41. 45
      src/autodoc/Helpers/Command/FromDirectory.php
  42. 49
      src/autodoc/Helpers/Command/FromGit.php
  43. 48
      src/autodoc/Helpers/Command/FromPlugin.php
  44. 49
      src/autodoc/Helpers/Command/FromSpip.php
  45. 47
      src/autodoc/Helpers/Command/FromSvn.php
  46. 48
      src/autodoc/Helpers/Command/FromZone.php
  47. 72
      src/autodoc/Helpers/phpdoc_helper.xml
  48. 72
      src/autodoc/Plugin/Core/Compiler/Pass/ApisCollector.php
  49. 125
      src/autodoc/Plugin/Core/Compiler/Pass/DirectoryTreeBuilder.php
  50. 65
      src/autodoc/Plugin/Core/Compiler/Pass/ErrorsCollector.php
  51. 119
      src/autodoc/Plugin/Core/Compiler/Pass/ExampleTagCorrector.php
  52. 67
      src/autodoc/Plugin/Core/Compiler/Pass/GetTopNav.php
  53. 51
      src/autodoc/Plugin/Core/Compiler/Pass/MarkersCollector.php
  54. 70
      src/autodoc/Plugin/Core/Compiler/Pass/SpipShare.php
  55. 283
      src/autodoc/Plugin/Core/Compiler/Pass/SpipTagsCollector.php
  56. 82
      src/autodoc/Plugin/Core/Compiler/Pass/Statistics.php
  57. 305
      src/autodoc/Plugin/Core/Compiler/Pass/UsedByTagBuilder.php
  58. 47
      src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/Finder.php
  59. 61
      src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/Git.php
  60. 24
      src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/None.php
  61. 73
      src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/Svn.php
  62. 196
      src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/VcsInformationsAbstract.php
  63. 211
      src/autodoc/Plugin/Core/Compiler/Pass/VcsLinkBuilder.php
  64. 120
      src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/DefaultViewer.php
  65. 29
      src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Gitea.php
  66. 39
      src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Github.php
  67. 39
      src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Gitlab.php
  68. 27
      src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Redmine.php
  69. 27
      src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Trac.php
  70. 46
      src/autodoc/Plugin/Core/Descriptor/ApiDescriptor.php
  71. 158
      src/autodoc/Plugin/Core/Descriptor/DirectoryDescriptor.php
  72. 29
      src/autodoc/Plugin/Core/Descriptor/Interfaces/DirectoryInterface.php
  73. 70
      src/autodoc/Plugin/Core/Descriptor/PipelineDescriptor.php
  74. 40
      src/autodoc/Plugin/Core/Descriptor/SpipTagDescriptor.php
  75. 10
      src/autodoc/Plugin/Core/Descriptor/UsedByTagDescriptor.php
  76. 49
      src/autodoc/Plugin/Core/Descriptor/Validator/ErrorCollector.php
  77. 83
      src/autodoc/Plugin/Core/ServiceProvider.php
  78. 23
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/ApiDescriptor.php
  79. 34
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/ConstantDescriptor.php
  80. 26
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/DirectoryDescriptor.php
  81. 25
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/FileDescriptor.php
  82. 25
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/FunctionDescriptor.php
  83. 38
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/PackageDescriptor.php
  84. 23
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/PipelineDescriptor.php
  85. 23
      src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/ProjectDescriptor.php
  86. 53
      src/autodoc/Plugin/Core/Transformer/Router/ZoraRouter.php
  87. 102
      src/autodoc/Plugin/Core/Transformer/Writer/FileCleaner.php
  88. 79
      src/autodoc/Plugin/Core/Transformer/Writer/FileConcat.php
  89. 52
      src/autodoc/Plugin/Core/Transformer/Writer/Twig.php
  90. 521
      src/autodoc/Plugin/Core/TwigZora.php
  91. 163
      templates/template/css/custom.css.twig
  92. 76
      templates/template/css/variables.css.twig
  93. 1
      templates/template/icons/constant.svg.twig
  94. 1
      templates/template/icons/method.svg.twig
  95. 4
      templates/zora/api.twig
  96. 4
      templates/zora/apis.twig
  97. 4
      templates/zora/balises.twig
  98. 38
      templates/zora/body.twig
  99. 6316
      templates/zora/bootstrap/css/bootstrap.css
  100. 874
      templates/zora/bootstrap/css/bootstrap.min.css
  101. Some files were not shown because too many files have changed in this diff Show More

156
.gitattributes vendored

@ -1,156 +0,0 @@
* text=auto !eol
bin/autodoc -text
bin/autodoc_helper -text
/composer.json -text
/installation.md -text
src/autodoc/Application.php -text
src/autodoc/Configuration.php -text
src/autodoc/Configuration/Option.php -text
src/autodoc/Configuration/Options.php -text
src/autodoc/Helpers/Application.php -text
src/autodoc/Helpers/Command/FromDirectory.php -text
src/autodoc/Helpers/Command/FromFile.php -text
src/autodoc/Helpers/Command/FromPlugin.php -text
src/autodoc/Helpers/Command/FromSpip.php -text
src/autodoc/Helpers/Command/FromSvn.php -text
src/autodoc/Helpers/Command/FromZone.php -text
src/autodoc/Helpers/Generator.php -text
src/autodoc/Helpers/Template/index.html -text
src/autodoc/Helpers/phpdoc_helper.xml -text
src/autodoc/Plugin/Core/Compiler/Pass/ApisCollector.php -text
src/autodoc/Plugin/Core/Compiler/Pass/DirectoryTreeBuilder.php -text
src/autodoc/Plugin/Core/Compiler/Pass/ErrorsCollector.php -text
src/autodoc/Plugin/Core/Compiler/Pass/ExampleTagCorrector.php -text
src/autodoc/Plugin/Core/Compiler/Pass/GetTopNav.php -text
src/autodoc/Plugin/Core/Compiler/Pass/MarkersCollector.php -text
src/autodoc/Plugin/Core/Compiler/Pass/SpipShare.php -text
src/autodoc/Plugin/Core/Compiler/Pass/SpipTagsCollector.php -text
src/autodoc/Plugin/Core/Compiler/Pass/Statistics.php -text
src/autodoc/Plugin/Core/Compiler/Pass/UsedByTagBuilder.php -text
src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/Svn.php -text
src/autodoc/Plugin/Core/Compiler/Pass/VcsInformations/VcsInformationsAbstract.php -text
src/autodoc/Plugin/Core/Compiler/Pass/VcsLinkBuilder.php -text
src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/DefaultViewer.php -text
src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Redmine.php -text
src/autodoc/Plugin/Core/Compiler/Pass/VcsViewer/Trac.php -text
src/autodoc/Plugin/Core/Descriptor/ApiDescriptor.php -text
src/autodoc/Plugin/Core/Descriptor/DirectoryDescriptor.php -text
src/autodoc/Plugin/Core/Descriptor/Interfaces/DirectoryInterface.php -text
src/autodoc/Plugin/Core/Descriptor/PipelineDescriptor.php -text
src/autodoc/Plugin/Core/Descriptor/SpipTagDescriptor.php -text
src/autodoc/Plugin/Core/Descriptor/UsedByTagDescriptor.php -text
src/autodoc/Plugin/Core/Descriptor/Validator/ErrorCollector.php -text
src/autodoc/Plugin/Core/ServiceProvider.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/ApiDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/ConstantDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/DirectoryDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/FileDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/FunctionDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/PackageDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/PipelineDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/UrlGenerator/Zora/ProjectDescriptor.php -text
src/autodoc/Plugin/Core/Transformer/Router/ZoraRouter.php -text
src/autodoc/Plugin/Core/Transformer/Writer/FileCleaner.php -text
src/autodoc/Plugin/Core/Transformer/Writer/FileConcat.php -text
src/autodoc/Plugin/Core/Transformer/Writer/Twig.php -text
src/autodoc/Plugin/Core/TwigZora.php -text
templates/zora/api.twig -text
templates/zora/apis.twig -text
templates/zora/balises.twig -text
templates/zora/body.twig -text
templates/zora/bootstrap/css/bootstrap.css -text
templates/zora/bootstrap/css/bootstrap.min.css -text
templates/zora/bootstrap/img/glyphicons-halflings-white.png -text
templates/zora/bootstrap/img/glyphicons-halflings.png -text
templates/zora/bootstrap/js/bootstrap.js -text
templates/zora/bootstrap/js/bootstrap.min.js -text
templates/zora/boucles.twig -text
templates/zora/breadcrumb/directory.twig -text
templates/zora/breadcrumb/package.twig -text
templates/zora/class.twig -text
templates/zora/classes.twig -text
templates/zora/constantes.twig -text
templates/zora/content/api.twig -text
templates/zora/content/apis.twig -text
templates/zora/content/balises.twig -text
templates/zora/content/boucles.twig -text
templates/zora/content/class.twig -text
templates/zora/content/classes.twig -text
templates/zora/content/constantes.twig -text
templates/zora/content/criteres.twig -text
templates/zora/content/deprecies.twig -text
templates/zora/content/directory.twig -text
templates/zora/content/dist.twig -text
templates/zora/content/erreurs.twig -text
templates/zora/content/file.twig -text
templates/zora/content/filtres.twig -text
templates/zora/content/marqueurs.twig -text
templates/zora/content/package.twig -text
templates/zora/content/packages.twig -text
templates/zora/content/pipeline.twig -text
templates/zora/content/pipelines.twig -text
templates/zora/content/recherche.twig -text
templates/zora/content/sommaire.twig -text
templates/zora/content/statistiques.twig -text
templates/zora/criteres.twig -text
templates/zora/css/perso.css -text
templates/zora/debug.twig -text
templates/zora/deprecies.twig -text
templates/zora/directory.twig -text
templates/zora/erreurs.twig -text
templates/zora/extra/dist.twig -text
templates/zora/favicon.png -text
templates/zora/file.twig -text
templates/zora/filtres.twig -text
templates/zora/footer/dist.twig -text
templates/zora/fqsen_data.twig -text
templates/zora/head-js/dist.twig -text
templates/zora/head/dist.twig -text
templates/zora/header/dist.twig -text
templates/zora/htaccess.twig -text
templates/zora/images/api-32.png -text
templates/zora/images/api-48.png -text
templates/zora/images/deprecated-48.png -text
templates/zora/images/loader-32.gif -text
templates/zora/images/logo.png -text
templates/zora/images/logo_mini.png -text
templates/zora/images/logo_petit.png -text
templates/zora/images/owl.png -text
templates/zora/inclure/ariane_et_titre_standard.twig -text
templates/zora/inclure/descriptions/argument.twig -text
templates/zora/inclure/descriptions/constants.twig -text
templates/zora/inclure/descriptions/functions.twig -text
templates/zora/inclure/descriptions/group_content.twig -text
templates/zora/inclure/descriptions/package.twig -text
templates/zora/inclure/descriptions/package_link.twig -text
templates/zora/inclure/descriptions/pipeline.twig -text
templates/zora/inclure/descriptions/properties.twig -text
templates/zora/inclure/descriptions/see.twig -text
templates/zora/inclure/descriptions/summary.twig -text
templates/zora/inclure/descriptions/tags.twig -text
templates/zora/inclure/descriptions/types.twig -text
templates/zora/inclure/head.twig -text
templates/zora/inclure/liste/packages.twig -text
templates/zora/inclure/liste/spiperies.twig -text
templates/zora/inclure/liste/spiperies_with_tabs.twig -text
templates/zora/inclure/nav-directory.twig -text
templates/zora/inclure/nav.twig -text
templates/zora/index.twig -text
templates/zora/js/dygraph-combined.js -text
templates/zora/js/jquery.min.js -text
templates/zora/js/perso.js -text
templates/zora/last_stat.twig -text
templates/zora/marqueurs.twig -text
templates/zora/more/dist.twig -text
templates/zora/navigation.twig -text
templates/zora/package.twig -text
templates/zora/packages.twig -text
templates/zora/pipeline.twig -text
templates/zora/pipelines.twig -text
templates/zora/recherche.twig -text
templates/zora/recherche_data.twig -text
templates/zora/statistiques.twig -text
templates/zora/statistiques.txt -text
templates/zora/structure.twig -text
templates/zora/template.xml -text
templates/zora/z_bloc.twig -text

2
.gitignore vendored

@ -1 +1,3 @@
/vendor
/build
/cache

103
README.md

@ -0,0 +1,103 @@
# Autodoc
## Installation
### Dépendences du serveur
php-intl graphviz
### Intallation de phpDocumentor
Télécharger la dernière archive phpDocumentor.phar dans son répertoire de travail.
https://github.com/phpDocumentor/phpDocumentor/releases
Exemple:
```bash
wget https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.3.0/phpDocumentor.phar
```
### Installation de l’application
```bash
git clone https://git.spip.net/spip-galaxie/code.spip.net_autodoc autodoc && cd autodoc
composer 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.
```bash
mkdir var
```
### Mises à jour
```bash
cd autodoc && git pull
composer update
cd ..
```
## Usage
Appel :
autodoc [command] [options]
L'exécutable sans paramètre affiche la liste des actions et peut afficher,
pour chaque action ses arguments et options possibles.
## Commandes
### 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 from:directory /home/marcimat/www/spip-dev
Forcer un préfixe de sortie ici dans `work/output/spip-dev` :
autodoc from:directory /home/marcimat/www/spip-dev --prefixe=spip-dev
### from:spip
Générer la documentation depuis le svn du core
autodoc from:spip
autodoc from:spip --branche=4.0
### from:zone
Générer la documentation depuis un chemin de la zone
autodoc from:zone spip-contrib-extensions/fabrique
### from:plugin
Générer la documentation depuis l'organisation spip-contrib-extensions de la zone
autodoc from:plugin fabrique
#### from:file
Générer des documentations dont les sources sont indiquées dans un fichier.
Par défaut, utilise le fichier autodoc.txt de la zone.
autodoc from:file
autodoc from:file autodoc.txt
autodoc from:file https://git.spip.net/spip-contrib-outils/archivelists/raw/branch/master/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 : `--outputs=chemin`
- le plugin généré (via son préfixe) : `--prefix=saisies`
- ou forcer la génération de la documentation, même si ce n'est pas nécessaire : `--force`

18
bin/autodoc

@ -11,19 +11,13 @@
* Pour un usage simplifié, utiliser autodoc_helper.php
*/
# charger l'autoloader
$bootstrap_folder = __DIR__ . '/../src';
$autoloader_base_path = '/../vendor/autoload.php';
$autoloader_location = $bootstrap_folder . $autoloader_base_path;
$autoloader = __DIR__ . '/../vendor/autoload.php';
if (! file_exists($autoloader_location) || ! is_readable($autoloader_location)) {
throw new \RuntimeException('Unable to find autoloader at ' . $autoloader_location);
if (! file_exists($autoloader) || ! is_readable($autoloader)) {
throw new \RuntimeException('Unable to find autoloader at ' . $autoloader);
}
$autoloader = require $autoloader_location;
$app = new autodoc\Application($autoloader);
$app->run();
require $autoloader;
$app = new Spip\Autodoc\Application();
$app->run();

29
bin/autodoc_helper

@ -1,29 +0,0 @@
#!/usr/bin/env php
<?php
/**
* Script pour simplifier l'usage de la génération de documentation
* dans le cadre du code source SPIP
*
* Ce script crée les répertoires nécessaires à son fonctionnement
* et utilise une configuration (phpdoc.xml) adaptée.
*
* Il nécessite un répertoire `work` accessible en écriture (le programme
* tentera de le créer s'il est absent). Toutes les données de travail et
* les productions seront mises dedans.
*/
# charger l'autoloader
$bootstrap_folder = __DIR__ . '/../src';
$autoloader_base_path = '/../vendor/autoload.php';
$autoloader_location = $bootstrap_folder . $autoloader_base_path;
if (! file_exists($autoloader_location) || ! is_readable($autoloader_location)) {
throw new \RuntimeException('Unable to find autoloader at ' . $autoloader_location);
}
$autoloader = require $autoloader_location;
# exécuter l'application
$app = new autodoc\Helpers\Application($autoloader);
$app->run();

14
composer.json

@ -1,14 +1,18 @@
{
"name": "marcimat/autodoc",
"name": "spip/autodoc",
"autoload": {
"psr-0":{
"autodoc": "src/"
"psr-4":{
"Spip\\Autodoc\\": "src/"
}
},
"require": {
"php": ">=5.6.0"
"php": ">=8.0.2",
"symfony/console": "^6.0",
"symfony/filesystem": "^6.0",
"psr/log": "^3.0",
"league/pipeline": "^1.0"
},
"require-dev": {
"phpdocumentor/phpdocumentor": "^2.9"
"symfony/var-dumper": "^6.0"
}
}

3415
composer.lock generated

File diff suppressed because it is too large Load Diff

219
installation.md

@ -1,219 +0,0 @@
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`

11
src/autodoc/Helpers/Command/FromFile.php → old/FromFile.php

@ -4,18 +4,17 @@
* Commande d'exécution depuis un fichier autodoc.txt (de la Zone de SPIP par défaut)…
*/
namespace autodoc\Helpers\Command;
namespace Spip\Autodoc\Command;
use Cilex\Command\Command;
use Spip\Autodoc\Generator;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use autodoc\Helpers\Generator;
use Symfony\Component\Console\Command\Command;
/**
* Déclaration et exécution de l'application depuis le svn d'un plugin de la zone de SPIP
* Déclaration et exécution de l'application depuis un fichier de type autodoc.txt
*/
class FromFile extends Command
{
@ -48,7 +47,7 @@ https://git.spip.net/spip-contrib-extensions/champs_extras_core@master;cextras
$output->writeln("\nExécuter autodoc sur un fichier : <info>$file</info>.");
$generator = new Generator($input, $output, $this->getApplication()->getService('autoloader'));
$generator = new Generator($input, $output);
$generator->generateFromFile($file);
}
}

294
src/autodoc/Helpers/Generator.php → old/GeneratorOld.php

@ -4,92 +4,50 @@
* Commande d'execution …
*/
namespace autodoc\Helpers;
namespace Spip\Autodoc;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\StringInput;
use Symfony\Component\Console\Input\ArgvInput;
use Symfony\Component\Console\Output\Output;
use autodoc\Application as Autodoc;
use Symfony\Component\Console\Logger\ConsoleLogger;
/**
* Exécuter l'application…
*/
class Generator
class GeneratorOld
{
private $input;
private $output;
private $autoloader;
private InputInterface $input;
private Output $output;
private $dirs = array();
private $files = array();
private $svn = array(); // informations sur le dépot SVN
private $git = array(); // informations sur le dépot GIT
private $options = array('dirs' => array()); // forcer des répertoires en dehors des options de ligne de commande
private $commands = array(); // forcer des commandes spécifiques à phpdocumentor
private $dirs = [];
private $files = [];
private Git $git; // informations sur le dépot GIT
private $options = ['dirs' => []]; // forcer des répertoires en dehors des options de ligne de commande
private $commands = []; // forcer des commandes spécifiques à phpdocumentor
// les infos de plugins sont enregistrées dedans pour l'index.html de la commande generateFromFile()
private $infos_plugins = array();
private $infos_plugins = [];
/**
* Description de la documentation à générer
* @var string $description */
private $description = "";
/** Description de la documentation à générer */
private string $description = "";
/**
* Présentation de la documentation à générer
* @var string $presentation */
private $presentation = "";
/** Présentation de la documentation à générer */
private string $presentation = "";
/**
* Constructeur
*
* @param InputInterface $input
* @param OutputInterface $output
**/
public function __construct(InputInterface $input, Output $output, $autoloader = null)
public function __construct(InputInterface $input, Output $output)
{
$this->input = $input;
$this->input = $input;
$this->output = $output;
$this->autoloader = $autoloader;
$this->setApplicationDirectories();
}
public function isVerbose() {
public function isVerbose() : bool {
return $this->output->isVerbose();
}
/**
* Obtient le chemin d'un executable sur le serveur.
*
* @example
* ```
* $cmd = $this->obtenir_commande_serveur('svn');
* if ($cmd)
* exec("$cmd ... ... ");
* }
* ```
* @param string $command
* Nom de la commande
* @return string
* Chemin de la commande
**/
public function obtenir_commande_serveur($command) {
static $commands = array();
if (array_key_exists($command, $commands)) {
return $commands[$command];
}
exec("command -v $command", $output, $err);
if (!$err and count($output) and $cmd = trim($output[0])) {
return $commands[$command] = $cmd;
}
$this->output->writeln("<error>Commande '$command' introuvable sur ce serveur…</error>");
return $commands[$command] = '';
}
/**
* Générer la documentation à partir du GIT de SPIP
@ -100,7 +58,6 @@ class Generator
**/
public function generateFromSpip($branche) {
$url = "https://git.spip.net/spip/spip.git";
$prefixe = $this->input->getOption('prefixe');
$ok = $this->createDirectories($prefixe)
@ -155,19 +112,6 @@ class Generator
return $ok;
}
/**
* Générer la documentation à partir d'une url SVN
*
* @param string $source URL SVN
**/
public function generateFromSvn($source) {
$prefixe = $this->input->getOption('prefixe');
$ok = $this->createDirectories($prefixe)
&& $this->getSvnSource($source)
&& $this->generateFromDirectory($this->dirs['input'], true);
return $ok;
}
/**
* Générer la documentation à partir d'un répertoire indiqué
@ -448,7 +392,7 @@ class Generator
* Télécharge la source de liste des documentations à faire dans autodoc.txt
* et fait une rotation avec l'ancienne liste
*
* @param strig $file
* @param string $file
* URL du fichier source (svn) de la liste des docémentations à générer
* @return bool True si ok.
**/
@ -593,9 +537,6 @@ class Generator
# ce répertoire
$this->dirs['helper'] = realpath(__DIR__);
# executable php de l'application autodoc (extension de l'application phpdocumentor)
$this->dirs['bin'] = realpath( $this->dirs['helper'] . '/../../../bin');
# répertoire racine (celui depuis lequel on execute ce script).
exec('pwd', $output);
$this->dirs['root'] = $output[0];
@ -683,64 +624,41 @@ class Generator
* Télécharge ou met à jour la source SVN indiquée
*
* @param string $source URL de la source Git
* @param string $branche Branche à utiliser
* @param string $branch Branche à utiliser
* @return bool true si réussi
**/
private function getGitSource($source, $branche, $type = 'git') {
private function getGitSource(string $source, string $branch, string $type = 'git') : bool {
$this->output->writeln("* Obtenir <info>$source</info>");
$this->git = array();
// si c'est en svn et le bon, on fait svn up simplement.
$res = $this->makeCheckoutCommand('--read');
if (!$res or false === stripos(implode("", $res), $source)) {
$checkout = $this->getCheckout();
$urlGit = $checkout->readGit()->getUrl();
if (!$urlGit or $urlGit !== $source) {
// erreur, donc pas un dossier ou pas le bon
$this->output->writeln("<comment> - Source absente ou mauvaise, on le recrée</comment>");
$this->deleteDirectoryContent($this->dirs['input'], true);
}
$res = $this->makeCheckoutCommand("$type -b$branche $source");
$checkout->run("$type -b$branch $source");
// On récupère le numéro de dernière révision, ça peut servir
if ($infos = $this->recuperer_infos_git()) {
$this->git['revision'] = $infos['revision'];
$this->git['branche'] = $infos['branche'];
}
$this->git = $checkout->readGit();
return true;
}
/**
* Retrouver le numéro de la dernière révision du dossier de travail
*
* @return string Numéro de révision (si connu)
**/
function recuperer_infos_git() {
$infos = [];
// Ici, on a les bons fichiers SVN à jour
// on récupère le numéro de dernière révision
if ($res = $this->makeCheckoutCommand('--read')) {
$res = trim($res[0]);
$res = explode(' ', $res);
$infos['revision'] = substr($res[2], 2); // -r{revision}
$infos['branche'] = substr($res[3], 2); // -b{branche}
$infos['url'] = $res[4];
}
return $infos;
}
/**
* Retrouver le numéro de la dernière révision du dossier de travail
* Retourne checkout
*
* @return string Numéro de révision (si connu)
* @param string $cmd Commande Checkout
* @param bool $no_error true : Envoie les erreurs dans /dev/null
* @return mixed|bool false en cas d'erreur
**/
function recuperer_revision_git() {
$infos = $this->recuperer_infos_git();
return $infos ? $infos['revision'] : '';
private function getCheckout() : Checkout {
$dir = $this->dirs['input'];
return new Checkout($dir, new ConsoleLogger($this->output));
}
/**
* Exécuter la commande checkout indiquée
*
@ -752,136 +670,11 @@ class Generator
if (is_null($dir)) {
$dir = $this->dirs['input'];
}
if (!$checkout = $this->obtenir_commande_serveur('checkout')) {
return false;
}
$no_error = $no_error ? '2> /dev/null' : '';
# checkout doit se lancer depuis le répertoire parent
$dest = basename($dir);
$root = dirname($dir);
$cmd = "cd $root && $checkout $cmd $dest $no_error";
if ($this->isVerbose()) {
$this->output->writeln($cmd);
}
exec($cmd, $res, $error);
if ($this->isVerbose()) {
$this->output->writeln($res);
}
if ($error) {
if ($this->isVerbose()) {
$this->output->writeln($error);
}
return false;
}
return $res;
$checkout = new Checkout($dir, new ConsoleLogger($this->output));
return $checkout->run($cmd);
}
/**
* Télécharge ou met à jour la source SVN indiquée
*
* @param string $source URL de la source SVN
* @return bool true si réussi
**/
private function getSvnSource($source) {
$this->output->writeln("* Obtenir <info>$source</info>");
$this->svn = array();
// si c'est en svn et le bon, on fait svn up simplement.
if ($res = $this->makeSvnCommand('info --xml')) {
// nous avons un svn… verifions que c'est le bon !
$xml = simplexml_load_string(implode("", $res));
$source_actuelle = (string)$xml->entry->url;
if ($source_actuelle == $source) {
#$this->output->write("<comment> - Update </comment>");
if (!$res = $this->makeSvnCommand("update")) {
$this->output->writeln("<error>[Echec Update]</error>");
return false;
}
$last = array_pop($res);
# $this->output->writeln("[<info>OK</info>] ($last)");
}
}
// erreur, donc pas un dossier svn ou pas le bon
else {
// on nettoie le contenu pour svn co
$this->deleteDirectoryContent($this->dirs['input']);
#$this->output->write("<comment> - Checkout </comment>");
if (!$res = $this->makeSvnCommand("checkout $source .")) {
$this->output->writeln("<error>[Echec Checkout]</error>");
return false;
}
$last = array_pop($res);
if ($last) $last = "($last)";
# $this->output->writeln("<info>[OK]</info> $last");
}
// On récupère le numéro de dernière révision, ça peut servir
if ($revision = $this->recuperer_revision_svn()) {
$this->svn['revision'] = $revision;
}
return true;
}
/**
* Retrouver le numéro de la dernière révision du dossier de travail
*
* @return string Numéro de révision (si connu)
**/
function recuperer_revision_svn() {
$revision = '';
// Ici, on a les bons fichiers SVN à jour
// on récupère le numéro de dernière révision
if ($res = $this->makeSvnCommand('info --xml')) {
// nous avons un svn… verifions que c'est le bon !
$xml = simplexml_load_string(implode("", $res));
$revision = (string)$xml->entry->commit['revision'];
}
return $revision;
}
/**
* Exécuter la commande svn indiquée
*
* @param string $cmd Commande SVN
* @param bool $no_error true : Envoie les erreurs dans /dev/null
* @return mixed|bool false en cas d'erreur
**/
private function makeSvnCommand($cmd, $no_error = true, $dir = null) {
if (is_null($dir)) {
$dir = $this->dirs['input'];
}
if (!$svn = $this->obtenir_commande_serveur('svn')) {
if (!$svn = $this->obtenir_commande_serveur('svnlite')) {
return false;
} else {
$this->output->writeln("<info>Commande 'svnlite' trouvée</info>");
}
}
$no_error = $no_error ? '2> /dev/null' : '';
exec("cd $dir && $svn $cmd $no_error", $res, $error);
if ($error) return false;
return $res;
}
/**
* Suppression du contenu d'un repertoire.
@ -1167,7 +960,7 @@ class Generator
**/
private function execute() {
$conf = $this->files['phpdoc.xml'];
$command = "project:run --config=$conf --parseprivate";
$command = "php phpDocumentor.phar --config=$conf";
if ($this->getOption('force')) {
$command .= " --force";
}
@ -1176,20 +969,7 @@ class Generator
$command .= $title;
}
// l'option --config=x de phpdocumentor (contrairement aux autres) n'est lue que via ArgvInput.
// de la sorte, pour transmettre cette option, on crée l'argv qui va bien. Ce n'est pas très glorieux !
$command_helper = $_SERVER['argv'];
$command = new StringInput("autodoc $command");
// pas moyen d'obtenir le tableau adapté directement… on triche par une réflexion.
$reflectedCommand = new \ReflectionClass('Symfony\Component\Console\Input\ArgvInput');
$tokens = $reflectedCommand->getProperty('tokens');
$tokens->setAccessible(true);
$_SERVER['argv'] = $tokens->getValue($command);
$app = new Autodoc( $this->autoloader );
$app->run();
$_SERVER['argv'] = $command_helper;
passthru($command);
}

5
src/autodoc/Helpers/Template/index.html → placeholders/index.html

@ -93,12 +93,9 @@
<div class='container'>
Liste automatique créée avec
<a href="https://zone.spip.org/trac/spip-zone/browser/_galaxie_/code.spip.net/autodoc/trunk">Autodoc</a>,
utilisant les logiciels <a href="http://cilex.github.io/">Cilex</a>
et <a href="http://twig.sensiolabs.org/">Twig</a>.<br />
<a href="https://git.spip.net/spip-galaxie/code.spip.net_autodoc">Autodoc</a>.<br />
Les documentations liées sont générées avec <a href="https://www.phpdoc.org/">PHPDocumentor</a><br />
Fichier généré le {{ "now"|date("j/m/Y à H:i") }}
</div><!-- .container -->
</footer>
{% endblock %}

56
placeholders/phpdoc.xml

@ -0,0 +1,56 @@
<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor
configVersion="3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="https://www.phpdoc.org"
xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd"
>
<paths>
<output>@OUTPUT_DIRECTORY@</output>
<cache>@CACHE_DIRECTORY@</cache>
</paths>
<title>@TITLE@</title>
<version number="latest">
<api format="php">
<source dsn="@INPUT_DIRECTORY@">
<path>.</path>
</source>
<output>api</output>
<ignore hidden="true" symlinks="true">
<path>**/tests/**</path>
<path>**/lang/**</path>
<path>**/lib/**</path>
<path>**/docs/**</path>
<path>config/**/*</path>
<path>IMG/**/*</path>
<path>local/**/*</path>
<path>tmp/**/*</path>
<path>squelettes-dist/**/*</path>
</ignore>
<!-- default-package-name>@DEFAULT_PACKAGE_NAME@</default-package-name -->
<include-source>true</include-source>
<markers>
<marker>TODO</marker>
<marker>FIXME</marker>
</markers>
</api>
<guide format="rst">
<source dsn="@INPUT_DIRECTORY@">
<path>docs</path>
</source>
<output>docs</output>
</guide>
</version>
<setting name="slogan" value="@SLOGAN@"/>
<setting name="description" value="@DESCRIPTION@"/>
<setting name="presentation" value="@PRESENTATION@"/>
<setting name="url_package" value="@URL_PACKAGE@"/>
<setting name="url_documentation" value="@URL_DOCUMENTATION@"/>
<setting name="url_development" value="@URL_DEVELOPMENT@"/>
<!--template name="string" location="string">
<parameter name="string" value="string"/>
</template -->
</phpdocumentor>

27
src/Application.php

@ -0,0 +1,27 @@
<?php
/**
* autodoc : phpDocumentor pour SPIP
*/
namespace Spip\Autodoc;
use Symfony\Component\Console\Application as ConsoleApplication;
class Application extends ConsoleApplication
{
public const VERSION = '2.0.0';
public function __construct()
{
parent::__construct('Autodoc', self::VERSION);
// liste des commandes
$this->add(new Command\FromSpip());
$this->add(new Command\FromPlugin());
$this->add(new Command\FromZone());
$this->add(new Command\FromGit());
$this->add(new Command\FromDirectory());
$this->add(new Command\FromFile());
}
}

79
src/Checkout.php

@ -0,0 +1,79 @@
<?php
namespace Spip\Autodoc;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
class Checkout {
/** Directory name */
private string $destination;
/** Path where we will run the checkout command */
private string $root;
/** Path of checkout executable */
private string $checkout;
private LoggerInterface $logger;
public function __construct(string $dir, ?LoggerInterface $logger = null)
{
$this->destination = basename($dir);
// the checkout command is run from parent directory
$this->root = dirname($dir);
$this->logger = $logger ?? new NullLogger();
$this->checkout = $this->findCommand('checkout') ?? throw new \RuntimeException('Checkout not found.');
}
public function run(string $command) {
$cmd = "cd {$this->root} && {$this->checkout} $command {$this->destination} 2> /dev/null";
$this->logger->info($cmd);
exec($cmd, $res, $error);
$this->logger->info(implode("\n", $res));
if ($error) {
$this->logger->error($error);
return false;
}
return $res;
}
public function read() {
return $this->run('--read');
}
/**
* Retrouver des infos du git
*/
function readGit(): Git {
// Ici, on a les bons fichiers SVN à jour
// on récupère le numéro de dernière révision
if ($res = $this->read()) {
$res = trim($res[0]);
$res = explode(' ', $res);
$git = new Git($res[4]);
$git->setCommit(substr($res[2], 2)); // -r{commit}
$git->setBranch(substr($res[3], 2)); // -b{branch}
return $git;
}
return new Git();
}
/**
* Obtient le chemin d'un executable sur le serveur
*/
private function findCommand(string $command) : string {
static $commands = [];
if (array_key_exists($command, $commands)) {
return $commands[$command];
}
exec("command -v $command", $result, $err);
if (!$err and count($result) and $cmd = trim($result[0])) {
return $commands[$command] = $cmd;
}
$this->logger->error("Command '$command' not found");
return $commands[$command] = '';
}
}

78
src/Command/FromDirectory.php

@ -0,0 +1,78 @@
<?php
/*
* Commande d'exécution depuis une source répertoire …
*/
namespace Spip\Autodoc\Command;
use League\Pipeline\InterruptibleProcessor;
use League\Pipeline\Pipeline;
use Spip\Autodoc\Context;
use Spip\Autodoc\Stage\CheckStage;
use Spip\Autodoc\Stage\PackageStage;
use Spip\Autodoc\Stage\PhpDocumentorConfigStage;
use Spip\Autodoc\Stage\PhpDocumentorStage;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Command\Command;
/**
* Déclaration et exécution de l'application depuis un répertoire…
*/
class FromDirectory extends Command
{
protected function configure()
{
$this
->setName('from:directory')
->setDescription('Exécuter l’autodoc sur un répertoire donné')
->setHelp('Si le répertoire cible est un plugin SPIP, certaines informations seront extraites du paquet.xml et du fichier de langue.')
->addArgument('source', InputArgument::REQUIRED, 'Chemin du répertoire. <comment>Exemple : "/home/user/www/spip/plugins/fabrique"</comment>')
->addOption('prefix', 'p', InputOption::VALUE_OPTIONAL, 'Préfixe servant au stockage des données si pas de paquet.xml <comment>Défaut: "default"</comment>')
->addOption('output', 'o', InputOption::VALUE_OPTIONAL, 'Répertoire recevant le HTML généré. Chemin absolu ou relatif au répertoire "work". <comment>Défaut: "var/output/{prefixe}"</comment>')
->addOption('topnav', null, InputOption::VALUE_OPTIONAL, 'URL d’un fichier JS à charger dans le head html. <comment>Exemple: "//boussole.spip.net/?page=spipnav.js&lang=fr"</comment>')
->addOption('topnav_spip', null, InputOption::VALUE_NONE, 'Intègre le JS de la boussole SPIP en entête topnav.')
->addOption('force', '', InputOption::VALUE_NONE, 'Force l’analyse de tous les fichiers, même s’ils n’ont pas été modifiés.');
}
protected function execute(InputInterface $input, OutputInterface $output)
{
$context = new Context($input, $output);
/** @var SymfonyStyle */
$io = $context->get('io');
$io->title("Autodoc " . $this->getName());
$source = $input->getArgument('source');
$io->text("Source: <info>$source</info>.");
$context->set('input_directory', $source);
$context->set('output_directory', $input->getOption('output'));
if ($input->hasOption('prefix')) {
$context->set('default_prefix', $input->getOption('prefix'));
}
$context->set('topnav', $input->getOption('topnav'));
$context->set('topnav_spip', $input->getOption('topnav_spip'));
$context->set('phpdocumentor_force', $input->getOption('force'));
$this->pipeline($context);
return Command::SUCCESS;
}
protected function pipeline(Context $context): void
{
$processor = new InterruptibleProcessor(fn (Context $context) => $context->empty('errors'));
$pipeline = (new Pipeline($processor))
->pipe(new CheckStage)
->pipe(new PackageStage)
->pipe(new PhpDocumentorConfigStage)
->pipe(new PhpDocumentorStage);
$pipeline->process($context);
}
}

96
src/Command/FromGit.php

@ -0,0 +1,96 @@
<?php
/*
* Commande d'exécution depuis une source git …
*/
namespace Spip\Autodoc\Command;
use League\Pipeline\InterruptibleProcessor;
use League\Pipeline\Pipeline;
use Spip\Autodoc\Context;
use Spip\Autodoc\Exception\AutodocException;
use Spip\Autodoc\Git;
use Spip\Autodoc\Stage\CheckStage;
use Spip\Autodoc\Stage\GitStage;
use Spip\Autodoc\Stage\PackageStage;
use Spip\Autodoc\Stage\PhpDocumentorConfigStage;
use Spip\Autodoc\Stage\PhpDocumentorStage;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Style\SymfonyStyle;
/**
* Déclaration et exécution de l'application depuis un git
*/
class FromGit extends Command
{
protected function configure()
{
$this
->setName('from:git')
->setDescription('Exécuter l’autodoc sur une source GIT donnée')
->setHelp('Si le répertoire cible est un plugin SPIP, certaines informations seront extraites du paquet.xml et du fichier de langue.')
->addArgument('source', InputArgument::REQUIRED, 'URL de la source GIT. <comment>Exemple : "https://git.spip.net/spip/spip.git"</comment>')
->addOption('branch', 'b', InputOption::VALUE_OPTIONAL, 'Branche ou tag à utiliser', 'master')
->addOption('prefix', 'p', InputOption::VALUE_OPTIONAL, 'Préfixe servant au stockage des données')
->addOption('output', 'o', InputOption::VALUE_OPTIONAL, 'Répertoire recevant le HTML généré. Chemin absolu ou relatif au répertoire "work". <comment>Défaut: "var/output/{prefixe}"</comment>')
->addOption('topnav', null, InputOption::VALUE_OPTIONAL, 'URL d’un fichier JS à charger dans le head html. <comment>Exemple: "//boussole.spip.net/?page=spipnav.js&lang=fr"</comment>')
->addOption('topnav_spip', null, InputOption::VALUE_NONE, 'Intègre le JS de la boussole SPIP en entête topnav.')
->addOption('force', '', InputOption::VALUE_NONE, 'Force l’analyse de tous les fichiers, même s’ils n’ont pas été modifiés.');
}
protected function execute(InputInterface $input, OutputInterface $output)
{
$context = new Context($input, $output);
/** @var SymfonyStyle */
$io = $context->get('io');
$io->title("Autodoc " . $this->getName());
if ($input->hasArgument('source')) {
$source = $input->getArgument('source');
$io->text("Source: <info>$source</info>.");
}
$source = $this->getRepository($source ?? null);
if (!$source) {
throw new AutodocException("Source must be provide");
}
$context->set('output_directory', $input->getOption('output'));
$context->set('default_prefix', $input->getOption('prefix') ?: pathinfo($source, \PATHINFO_FILENAME));
$context->set('topnav', $input->getOption('topnav'));
$context->set('topnav_spip', $input->getOption('topnav_spip'));
$context->set('phpdocumentor_force', $input->getOption('force'));
$branch = $input->getOption('branch');
$git = (new Git($source))->setBranch($branch);
$context->set('git_asked', $git);
$this->pipeline($context);
return Command::SUCCESS;
}
protected function pipeline(Context $context): void
{
$processor = new InterruptibleProcessor(fn (Context $context) => $context->empty('errors'));
$pipeline = (new Pipeline($processor))
->pipe(new CheckStage)
->pipe(new GitStage)
->pipe(new PackageStage)
->pipe(new PhpDocumentorConfigStage)
->pipe(new PhpDocumentorStage);
$pipeline->process($context);
}
protected function getRepository(?string $source = null): ?string
{
return $source;
}
}

43
src/Command/FromPlugin.php

@ -0,0 +1,43 @@
<?php
/*
* Commande d'exécution depuis un plugin svn de la Zone de SPIP…
*/
namespace Spip\Autodoc\Command;
use Spip\Autodoc\Generator;
use Spip\Autodoc\Git;
use Spip\Autodoc\Loader;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Style\SymfonyStyle;
/**
* Déclaration et exécution de l'application depuis le svn d'un plugin de la zone de SPIP
*/
class FromPlugin extends FromGit
{
protected function configure()
{
$this
->setName('from:plugin')
->setDescription('Exécuter l’autodoc sur un plugin de la Zone')
->setHelp('Certaines informations seront extraites du paquet.xml et du fichier de langue.')
->addArgument('source', InputArgument::REQUIRED, 'Chemin depuis spip-contrib-extensions du Git de la zone. <comment>Exemple: "fabrique"</comment>')
->addOption('branch', 'b', InputOption::VALUE_OPTIONAL, 'Branche ou tag à utiliser', 'master')
->addOption('prefix', 'p', InputOption::VALUE_OPTIONAL, 'Préfixe servant au stockage des données si pas de paquet.xml <comment>Défaut: "default"</comment>')
->addOption('output', 'o', InputOption::VALUE_OPTIONAL, 'Répertoire recevant le HTML généré. Chemin absolu ou relatif au répertoire "work". <comment>Défaut: "var/output/{prefixe}"</comment>')
->addOption('topnav', null, InputOption::VALUE_OPTIONAL, 'URL d’un fichier JS à charger dans le head html. <comment>Exemple: "//boussole.spip.net/?page=spipnav.js&lang=fr"</comment>')
->addOption('topnav_spip', null, InputOption::VALUE_NONE, 'Intègre le JS de la boussole SPIP en entête topnav.')
->addOption('force', '', InputOption::VALUE_NONE, 'Force l’analyse de tous les fichiers, même s’ils n’ont pas été modifiés.');
}
protected function getRepository(?string $source = null): ?string
{
return $source ? 'https://git.spip.net/spip-contrib-extensions/' . $source . '.git' : null;
}
}

60
src/Command/FromSpip.php

@ -0,0 +1,60 @@
<?php
/*
* Commande d'exécution depuis une source svn du core de SPIP…
*/
namespace Spip\Autodoc\Command;
use League\Pipeline\InterruptibleProcessor;
use League\Pipeline\Pipeline;
use Spip\Autodoc\Context;
use Spip\Autodoc\Stage\CheckStage;
use Spip\Autodoc\Stage\GitSpipStage;
use Spip\Autodoc\Stage\PackageStage;
use Spip\Autodoc\Stage\PhpDocumentorConfigStage;
use Spip\Autodoc\Stage\PhpDocumentorStage;
use Symfony\Component\Console\Input\InputOption;
/**
* Déclaration et exécution de l'application depuis le svn du core de SPIP
*/
class FromSpip extends FromGit
{
protected function configure()
{
$this
->setName('from:spip')
->setDescription('Exécuter l’autodoc sur le code de SPIP')
->addOption('branch', 'b', InputOption::VALUE_OPTIONAL, 'Branche ou tag à utiliser', 'master')
->addOption('prefix', 'p', InputOption::VALUE_OPTIONAL, 'Préfixe servant au stockage des données si pas de paquet.xml <comment>Défaut: "default"</comment>')
->addOption('output', 'o', InputOption::VALUE_OPTIONAL, 'Répertoire recevant le HTML généré. Chemin absolu ou relatif au répertoire "work". <comment>Défaut: "var/output/{prefixe}"</comment>')
->addOption('topnav', null, InputOption::VALUE_OPTIONAL, 'URL d’un fichier JS à charger dans le head html. <comment>Exemple: "//boussole.spip.net/?page=spipnav.js&lang=fr"</comment>')
->addOption('topnav_spip', null, InputOption::VALUE_NONE, 'Intègre le JS de la boussole SPIP en entête topnav.')
->addOption('force', '', InputOption::VALUE_NONE, 'Force l’analyse de tous les fichiers, même s’ils n’ont pas été modifiés.')
#->addOption('title', '', InputOption::VALUE_OPTIONAL, 'Titre du projet. Utilise le nom de la branche par défaut.')
#->addOption('description', '', InputOption::VALUE_OPTIONAL, 'Description du projet. Prédéfini sur le titre par défaut.')
#->addOption('presentation', '', InputOption::VALUE_OPTIONAL, 'Présentation du projet. Vide par défaut.')
;
}
protected function getRepository(?string $source = null): ?string
{
return 'https://git.spip.net/spip/spip.git';
}
protected function pipeline(Context $context): void
{
$processor = new InterruptibleProcessor(fn (Context $context) => $context->empty('errors'));
$pipeline = (new Pipeline($processor))
->pipe(new CheckStage)
->pipe(new GitSpipStage)
->pipe(new PackageStage)
->pipe(new PhpDocumentorConfigStage)
->pipe(new PhpDocumentorStage);
$pipeline->process($context);
}
}

43
src/Command/FromZone.php

@ -0,0 +1,43 @@
<?php
/*
* Commande d'exécution depuis une source svn de la Zone de SPIP…
*/
namespace Spip\Autodoc\Command;
use Spip\Autodoc\Generator;
use Spip\Autodoc\Git;
use Spip\Autodoc\Loader;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Style\SymfonyStyle;
/**
* Déclaration et exécution de l'application depuis le Git de la zone de SPIP
*/
class FromZone extends FromGit
{
protected function configure()
{
$this
->setName('from:zone')
->setDescription('Exécuter l’autodoc sur un répertoire de la Zone')
->setHelp('Si le répertoire cible est un plugin SPIP, certaines, certaines informations seront extraites du paquet.xml et du fichier de langue.')
->addArgument('source', InputArgument::REQUIRED, 'Chemin dans l’arborescence du git de la zone. <comment>Exemple: "spip-contrib-extensions/fabrique"</comment>')
->addOption('branch', 'b', InputOption::VALUE_OPTIONAL, 'Branche ou tag à utiliser', 'master')
->addOption('prefix', 'p', InputOption::VALUE_OPTIONAL, 'Préfixe servant au stockage des données si pas de paquet.xml <comment>Défaut: "default"</comment>')
->addOption('output', 'o', InputOption::VALUE_OPTIONAL, 'Répertoire recevant le HTML généré. Chemin absolu ou relatif au répertoire "work". <comment>Défaut