Browse Source

Tout début d'une application pour simplifier l'usage du programme.

La doc de ce programme est écrite… avant d'être fonctionnelle…
svn/root/trunk
marcimat@rezo.net 9 years ago
parent
commit
83ad0086da
  1. 4
      .gitattributes
  2. 10
      bin/autodoc.php
  3. 21
      bin/autodoc_helper.php
  4. 2
      composer.json
  5. 98
      installation.md
  6. 42
      src/autodoc/Helpers/Command/FromSvn.php
  7. 99
      src/autodoc/Helpers/Generator.php
  8. 56
      src/autodoc/Helpers/phpdoc_helper.xml

4
.gitattributes vendored

@ -1,8 +1,12 @@
* text=auto !eol
bin/autodoc.php -text
bin/autodoc_helper.php -text
/composer.json -text
/installation.md -text
src/autodoc/Application.php -text
src/autodoc/Helpers/Command/FromSvn.php -text
src/autodoc/Helpers/Generator.php -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

10
bin/autodoc.php

@ -4,12 +4,14 @@
* Autodoc.
*
* phpDocumentor pour le code source de SPIP
*
* Cet exécutable charge l'application autodoc (= phpdocumentor + plugins pour SPIP)
* et utilise les mêmes arguments d'entrée que l'application phpDocumentor.
*
* Pour un usage simplifié, utiliser autodoc_helper.php
*/
// determine base include folder, if @php_dir@ contains @php_dir then
// we did not install via PEAR
$bootstrap_folder = __DIR__ . '/../src';
require_once __DIR__ . '/../src/autodoc/Application.php';
require_once $bootstrap_folder . '/autodoc/Application.php';
$app = new autodoc\Application();
$app->run();

21
bin/autodoc_helper.php

@ -0,0 +1,21 @@
#!/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
require_once __DIR__ . '/../src/autodoc/Application.php';
# exécuter l'application
$app = new \Cilex\Application('Autodoc Generator Helper', '1.0.0');
$app->command(new autodoc\Helpers\Command\FromSvn());
$app->run();

2
composer.json

@ -2,7 +2,7 @@
"name": "marcimat/autodoc",
"autoload": {
"psr-0":{
"autodoc": ["src/"]
"autodoc": "src/"
}
},
"require": {

98
installation.md

@ -12,12 +12,21 @@ Dépendences du serveur :
Installation :
--------------
mkdir output && mkdir log
svn co svn://zone.spip.org/spip-zone/_galaxie_/code.spip.net/autodoc/trunk autodoc && cd autodoc
curl -sS https://getcomposer.org/installer | php
php composer.phar install
cd ..
En fonction de l'usage et du contenu de phpdoc.xml, il faudra créer un/des répertoires avec accès en écriture.
* Avec l'application `autodoc/bin/autodoc_helper.php` :
mkdir work
* Avec l'executable `autodoc/bin/autodoc.php` (et en fonction du phpdoc.xml) :
mkdir output && mkdir log
Mises à jour :
--------------
@ -39,14 +48,33 @@ Notes sur les mises à jour:
USAGE
=====
Il y a deux exécutables disponibles.
* L'un `autodoc.php` est l'équivalent de l'exécutable de phpdocumentor
mais charge en plus le plugins SPIP pour phpdocumentor.
* L'autre `autodoc_helper.php` est une application simplifiant l'utilisation
en préconfigurant les commandes à transmettre à l'exécutable.
Elle gère également le téléchargement des sources PHP à documenter.
Exécutable autodoc.php
----------------------
Appel :
php autodoc/bin/autodoc.php
Le fonctionnement est exactement le même que le script `phpdoc.php`
http://www.phpdoc.org/docs/latest/for-users/basic-usage.html
L'exécutable sans paramètre affiche la liste des actions et peut afficher,
pour chaque action ses arguments et options possibles.
### Appeler le template `zora`
Appeler le template `zora`
--------------------------
Par commande :
@ -68,8 +96,9 @@ Dans le fichier de configuration :
</phpdocumentor>
Autres options de configuration
-------------------------------
### 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 :
@ -94,3 +123,62 @@ qui agissent uniquement avec le template Zora :
si présent, ajoute cette information sur le sommaire de la documentation automatique générée.
- presentation :
si présent, ajoute cette information sur le sommaire de la documentation automatique générée.
Exécutable autodoc_helper.php
-----------------------------
Appel :
php autodoc/bin/autodoc_helper.php
L'exécutable sans paramètre affiche la liste des actions et peut afficher,
pour chaque action ses arguments et options possibles.
### Quelques commandes et exemples
#### from:svn
Générer la documentation depuis une source SVN quelconque.
Par défaut, la sortie est enregistrée dans le répertoire `work/output/default`
php autodoc/bin/autodoc_helper.php from:svn svn://trac.rezo.net/spip/spip
Forcer un préfixe de sortie ici dans `work/output/spip-dev` :
php autodoc/bin/autodoc_helper.php from:svn svn://trac.rezo.net/spip/spip --prefixe=spip-dev
#### from:spip
Générer la documentation depuis le svn du core
php autodoc/bin/autodoc_helper.php from:spip spip
php autodoc/bin/autodoc_helper.php from:spip branches/spip-3.0
#### from:zone
Générer la documentation depuis le svn de la zone
php autodoc/bin/autodoc_helper.php from:zone _plugins_/fabrique/trunk
#### from:plugin
Générer la documentation depuis le svn _plugins_ de la zone
php autodoc/bin/autodoc_helper.php from:plugin fabrique/trunk
#### from:file
Générer des documentations dont les sources sont indiquées dans un fichier
php autodoc/bin/autodoc_helper.php from:file autodoc.txt
php autodoc/bin/autodoc_helper.php from:file svn://zone.spip.org/spip-zone/autodoc.txt

42
src/autodoc/Helpers/Command/FromSvn.php

@ -0,0 +1,42 @@
<?php
/*
* Commande d'execution …
*/
namespace autodoc\Helpers\Command;
use Cilex\Command\Command;
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;
/**
* Exécuter l'application…
*/
class FromSvn extends Command
{
protected function configure()
{
$this
->setName('from:svn')
->setDescription("Exécuter l'autodoc sur une source SVN donnée")
->addArgument('source', InputArgument::REQUIRED, "URL de la source SVN")
#->addArgument('source', InputArgument::OPTIONAL, "URL de la source SVN")
#->addOption('yell', null, InputOption::VALUE_NONE, 'If set, the task will yell in uppercase letters')
;
}
protected function execute(InputInterface $input, OutputInterface $output)
{
$source = $input->getArgument('source');
$output->writeln("Exécuter <info>autodoc</info> avec <info>$source</info>.");
$generator = new Generator($input, $output);
$generator->generateFromSvn($source);
}
}

99
src/autodoc/Helpers/Generator.php

@ -0,0 +1,99 @@
<?php
/*
* Commande d'execution …
*/
namespace autodoc\Helpers;
use Cilex\Command\Command;
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;
/**
* Exécuter l'application…
*/
class Generator
{
private $input;
private $output;
private $dirs = array();
public function __construct(InputInterface $input, OutputInterface $output)
{
$this->input = $input;
$this->output = $output;
# 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];
# répertoire de travail (celui où on écrira tout).
$this->dirs['work'] = $this->dirs['root'] . '/work';
}
/**
* Générer la documentation à partir d'une url SVN
*
* @param string $source URL SVN
**/
public function generateFromSvn($source) {
$prefixe = 'default';
$this->createDirectories($prefixe);
}
/**
* Crée les répertoires nécessaires au fonctionnement de ce programme
*
* @param string $prefixe Préfixe utilisé pour cette génération
* @return bool true si réussi
**/
private function createDirectories($prefixe) {
$_work = $this->dirs['work'];
$this->output->writeln("* Vérifier/créer les répertoires de travail dans <info>$_work</info>.");
$this->createDirectory("output/$prefixe");
$this->createDirectory("input/$prefixe");
$this->createDirectory("log/$prefixe");
$this->createDirectory("cache/$prefixe");
}
/**
* Créer un des répertoires d'utilisation
*
* Vérifie également que le répertoire est utilisable en écriture.
*
* @param string $chemin Répertoire à créer
* @return bool true si réussi
**/
private function createDirectory($dir) {
$_dir = $this->dirs['work'] . '/' . $dir;
if (!is_dir($_dir)) {
$this->output->writeln(" - Création du répertoire <info>$dir</info>");
if (!@mkdir($_dir, 0755, true)) {
$this->output->writeln("<error>Impossible de créer le répertoire : $_dir</error>");
$error = error_get_last();
$this->output->writeln($error['message']);
return false;
}
}
if (!is_writable($_dir)) {
$this->output->writeln("<error>Le répertoire $_dir n'est pas accessible en écriture</error>");
return false;
}
return true;
}
}

56
src/autodoc/Helpers/phpdoc_helper.xml

@ -0,0 +1,56 @@
<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor>
<parser>
<default-package-name>SPIP</default-package-name>
<encoding>utf-8</encoding>
<target>work/cache/@PREFIXE@</target>
<markers>
<item>TODO</item>
<item>FIXME</item>
</markers>
<extensions>
<extension>php</extension>
</extensions>
<visibility></visibility>
</parser>
<files>
<ignore-hidden>on</ignore-hidden>
<ignore-symlinks>on</ignore-symlinks>
<ignore>tmp/*</ignore>
<ignore>lang/*</ignore>
<ignore>tests/*</ignore>
<ignore>test/*</ignore>
<ignore>config/*</ignore>
<ignore>IMG/*</ignore>
<ignore>local/*</ignore>
<ignore>tmp/*</ignore>
<!-- ignore lib/ mais aussi svp/lib -->
<ignore>lib/*</ignore>
<ignore>squelettes-dist/*</ignore>
</files>
<transformer>
<target>work/output/@PREFIXE@</target>
</transformer>
<logging>
<level>warn</level>
<paths>
<default>work/log/@PREFIXE@/phpdoc-{DATE}.log</default>
<errors>work/log/@PREFIXE@/phpdoc-{DATE}.errors.log</errors>
</paths>
</logging>
<transformations>
<template name="autodoc/templates/zora" />
</transformations>
<options>
<site value="http://code.spip.net/" />
<proposer value="oui" />
<description value="Documentation automatique du code PHP de SPIP." />
<presentation value="Cette documentation est extraite automatiquement à partir du code source
PHP de la version en développement de SPIP." />
<!--chemin value="autodoc/" / -->
</options>
</phpdocumentor>
Loading…
Cancel
Save