Browse Source
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
194 changed files with 2114 additions and 20204 deletions
@ -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 |
||||
@ -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` |
||||
@ -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(); |
||||
@ -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" |
||||
} |
||||
} |
||||
|
||||
@ -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&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` |
||||
@ -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> |
||||
@ -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()); |
||||
} |
||||
} |
||||
|
||||
@ -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] = ''; |
||||
} |
||||
|
||||
} |
||||