overhaul maintenance/mwdocgen.php

Now based on Maintenance class.
Reinstate {{EXCLUDE}} which got removed by 8199984

This is roughly back compatible.

bug: 34436
Change-Id: Ic1a2b2c29718054ec740b2ffb90350af700a6a58

diff --git a/maintenance/Doxyfile b/maintenance/Doxyfile
index e6862ac..5d40c16 100644 (file)
--- a/maintenance/Doxyfile
+++ b/maintenance/Doxyfile
@@ -176,6 +176,7 @@ FILE_PATTERNS          = *.c \
                          *.txt \
                          README
 RECURSIVE              = YES
                          *.txt \
                          README
 RECURSIVE              = YES

+EXCLUDE                = {{EXCLUDE}}

 EXCLUDE_SYMLINKS       = YES
 EXCLUDE_PATTERNS       = LocalSettings.php AdminSettings.php StartProfiler.php .svn */.git/* {{EXCLUDE_PATTERNS}}
 EXCLUDE_SYMBOLS        =
 EXCLUDE_SYMLINKS       = YES
 EXCLUDE_PATTERNS       = LocalSettings.php AdminSettings.php StartProfiler.php .svn */.git/* {{EXCLUDE_PATTERNS}}
 EXCLUDE_SYMBOLS        =

diff --git a/maintenance/mwdocgen.php b/maintenance/mwdocgen.php
index 3439b74..9283264 100644 (file)
--- a/maintenance/mwdocgen.php
+++ b/maintenance/mwdocgen.php
@@ -8,12 +8,6 @@
  * Usage:
  *   php mwdocgen.php
  *
  * Usage:
  *   php mwdocgen.php
  *

- * KNOWN BUGS:
- *
- * - pass_thru seems to always use buffering (even with ob_implicit_flush()),
- * that make output slow when doxygen parses language files.
- * - the menu doesnt work, got disabled at revision 13740. Need to code it.
- *

  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or


@@ -39,258 +33,126 @@
  * @version first release
  */
 
  * @version first release
  */
 

-#
-# Variables / Configuration
-#
-
-if ( PHP_SAPI != 'cli' ) {
-       echo 'Run "' . __FILE__ . '" from the command line.';
-       die( -1 );
-}
-
-/** Figure out the base directory for MediaWiki location */
-$mwPath = dirname( __DIR__ ) . DIRECTORY_SEPARATOR;
-
-/** doxygen binary script */
-$doxygenBin = 'doxygen';
-
-/** doxygen configuration template for mediawiki */
-$doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
-
-/** doxygen input filter to tweak source file before they are parsed */
-$doxygenInputFilter = "php {$mwPath}maintenance/mwdoc-filter.php";
-
-/** where Phpdoc should output documentation */
-$doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR;
-
-$doxyVersion = 'master';
-
-/** MediaWiki subpaths */
-$mwPathI = $mwPath . 'includes/';
-$mwPathL = $mwPath . 'languages/';
-$mwPathM = $mwPath . 'maintenance/';
-$mwPathS = $mwPath . 'skins/';
-
-/** Ignored paths relative to $mwPath */
-$mwExcludePaths = array(
-       'images',
-       'static',
-);
-
-/** Variable to get user input */
-$input = '';
-$excludePatterns = '';
-/** Whether to generates man pages: */
-$doxyGenerateMan = false;
-
-#
-# Functions
-#
-
-define( 'MEDIAWIKI', true );
-require_once "$mwPath/includes/GlobalFunctions.php";
-
-/**
- * Read a line from the shell
- * @param $prompt String
- * @return string
- */
-function readaline( $prompt = '' ) {
-       print $prompt;
-       $fp = fopen( "php://stdin", "r" );
-       $resp = trim( fgets( $fp, 1024 ) );
-       fclose( $fp );
-       return $resp;
-}
+require_once __DIR__ . '/Maintenance.php';

 
 /**
 
 /**

- * Generate a configuration file given user parameters and return the temporary filename.
- * @param $doxygenTemplate String: full path for the template.
- * @param $outputDirectory String: directory where the stuff will be output.
- * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path).
- * @param $currentVersion String: Version number of the software
- * @param $input String: Path to analyze.
- * @param $exclude String: Additionals path regex to exclude
- * @param $excludePatterns String: Additionals path regex to exclude
- *                 (LocalSettings.php, AdminSettings.php, .svn and .git directories are always excluded)
- * @param $doxyGenerateMan Boolean
- * @return string
+ * Maintenance script that builds doxygen documentation.
+ * @ingroup Maintenance

  */
  */

-function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $input, $exclude, $excludePatterns, $doxyGenerateMan, $doxygenInputFilter ) {
-
-       $template = file_get_contents( $doxygenTemplate );
-       // Replace template placeholders by correct values.
-       $replacements = array(
-               '{{OUTPUT_DIRECTORY}}' => $outputDirectory,
-               '{{STRIP_FROM_PATH}}' => $stripFromPath,
-               '{{CURRENT_VERSION}}' => $currentVersion,
-               '{{INPUT}}' => $input,
-               '{{EXCLUDE}}' => $exclude,
-               '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
-               '{{HAVE_DOT}}' => `which dot` ? 'YES' : 'NO',
-               '{{GENERATE_MAN}}' => $doxyGenerateMan ? 'YES' : 'NO',
-               '{{INPUT_FILTER}}' => $doxygenInputFilter,
-       );
-       $tmpCfg = str_replace( array_keys( $replacements ), array_values( $replacements ), $template );
-       $tmpFileName = tempnam( wfTempDir(), 'mwdocgen-' );
-       file_put_contents( $tmpFileName, $tmpCfg ) or die( "Could not write doxygen configuration to file $tmpFileName\n" );
-
-       return $tmpFileName;
-}
-
-#
-# Main !
-#
-
-unset( $file );
+class MWDocGen extends Maintenance {
+
+       /**
+        * Prepare Maintenance class
+        */
+       public function __construct() {
+               parent::__construct();
+               $this->mDescription = 'Build doxygen documentation';
+
+               $this->addOption( 'doxygen',
+                       'Path to doxygen',
+                       false, true );
+               $this->addOption( 'version',
+                       'Pass a MediaWiki version',
+                       false, true );
+               $this->addOption( 'generate-man',
+                       'Whether to generate man files' );
+               $this->addOption( 'file',
+                       'Only process given file (relative to $IP)',
+                       false, true );
+               $this->addOption( 'output',
+                       'Path to write doc to',
+                       false, true );
+               $this->addOption( 'no-extensions',
+                       'Ignore extensions' );
+       }

 
 

-if ( is_array( $argv ) ) {
-       for ( $i = 0; $i < count( $argv ); $i++ ) {
-               switch ( $argv[$i] ) {
-               case '--all':
-                       $input = 0;
-                       break;
-               case '--includes':
-                       $input = 1;
-                       break;
-               case '--languages':
-                       $input = 2;
-                       break;
-               case '--maintenance':
-                       $input = 3;
-                       break;
-               case '--skins':
-                       $input = 4;
-                       break;
-               case '--file':
-                       $input = 5;
-                       $i++;
-                       if ( isset( $argv[$i] ) ) {
-                               $file = $argv[$i];
-                       }
-                       break;
-               case '--no-extensions':
-                       $input = 6;
-                       break;
-               case '--output':
-                       $i++;
-                       if ( isset( $argv[$i] ) ) {
-                               $doxyOutput = realpath( $argv[$i] );
-                       }
-                       break;
-               case '--version':
-                       $i++;
-                       if ( isset( $argv[$i] ) ) {
-                               $doxyVersion = $argv[$i];
-                       }
-                       break;
-               case '--generate-man':
-                       $doxyGenerateMan = true;
-                       break;
-               case '--help':
-                       print <<<END
-Usage: php mwdocgen.php [<command>] [<options>]
+       public function getDbType() {
+               return Maintenance::DB_NONE;
+       }

 
 

-Commands:
-    --all           Process entire codebase
-    --includes      Process only files in includes/ dir
-    --languages     Process only files in languages/ dir
-    --maintenance   Process only files in maintenance/ dir
-    --skins         Process only files in skins/ dir
-    --file <file>   Process only the given file
-    --no-extensions Process everything but extensions directorys
+       protected function init() {
+               global $IP;
+
+               $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
+               $this->mwVersion = $this->getOption( 'version', 'master' );
+               $this->input = $IP . '/' . $this->getOption( 'file', '' );
+               $this->output = $this->getOption( 'output', "$IP/docs" );
+
+               $this->inputFilter = wfShellWikiCmd(
+                       $IP . '/maintenance/mwdoc-filter.php' );
+               $this->template = $IP . '/maintenance/Doxyfile';
+               $this->excludes = array(
+                       'images',
+                       'static',
+               );
+               $this->excludePatterns = array();
+               if ( $this->hasOption( 'no-extensions' ) ) {
+                       $this->excludePatterns[] = 'extensions';
+               }

 
 

-If no command is given, you will be prompted.
+               $this->doDot = `which dot`;
+               $this->doMan = $this->hasOption( 'generate-man' );
+       }

 
 

-Other options:
-    --output <dir>  Set output directory (default: $doxyOutput)
-    --generate-man  Generates man page documentation
-    --version       Project version to display in the outut (default: $doxyVersion)
-    --help          Show this help and exit.
+       public function execute() {
+               global $IP;

 
 

+               $this->init();

 
 

-END;
-                       exit( 0 );
-                       break;
+               # Build out directories we want to exclude
+               $exclude = '';
+               foreach ( $this->excludes as $item ) {
+                       $exclude .= " $IP/$item";

                }
                }

-       }
-}
-
-// TODO : generate a list of paths ))

 
 

-if ( $input === '' ) {
-       echo <<<OPTIONS
-Several documentation possibilities:
- 0 : whole documentation (1 + 2 + 3 + 4)
- 1 : only includes
- 2 : only languages
- 3 : only maintenance
- 4 : only skins
- 5 : only a given file
- 6 : all but the extensions directory
-OPTIONS;
-       while ( !is_numeric( $input ) ) {
-               $input = readaline( "\nEnter your choice [0]:" );
-               if ( $input == '' ) {
-                       $input = 0;
+               $excludePatterns = implode( ' ', $this->excludePatterns );
+
+               $conf = strtr( file_get_contents( $this->template ),
+                       array(
+                               '{{OUTPUT_DIRECTORY}}' => $this->output,
+                               '{{STRIP_FROM_PATH}}' => $IP,
+                               '{{CURRENT_VERSION}}' => $this->mwVersion,
+                               '{{INPUT}}' => $this->input,
+                               '{{EXCLUDE}}' => $exclude,
+                               '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
+                               '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
+                               '{{GENERATE_MAN}}' => $this->doMan ? 'YES' : 'NO',
+                               '{{INPUT_FILTER}}' => $this->inputFilter,
+                       )
+               );
+
+               $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
+               if ( file_put_contents( $tmpFile, $conf ) === false ) {
+                       $this->error( "Could not write doxygen configuration to file $tmpFile\n",
+                               /** exit code: */ 1 );

                }
                }

-       }
-}
-
-switch ( $input ) {
-case 0:
-       $input = $mwPath;
-       break;
-case 1:
-       $input = $mwPathI;
-       break;
-case 2:
-       $input = $mwPathL;
-       break;
-case 3:
-       $input = $mwPathM;
-       break;
-case 4:
-       $input = $mwPathS;
-       break;
-case 5:
-       if ( !isset( $file ) ) {
-               $file = readaline( "Enter file name $mwPath" );
-       }
-       $input = $mwPath . $file;
-       break;
-case 6:
-       $input = $mwPath;
-       $excludePatterns = 'extensions';
-}

 
 

-// Generate path exclusions
-$excludedPaths = $mwPath . join( " $mwPath", $mwExcludePaths );
-print "EXCLUDE: $excludedPaths\n\n";
+               $command = $this->doxygen . ' ' . $tmpFile;
+               $this->output( "Executing command:\n$command\n" );

 
 

-$generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $doxyVersion, $input, $excludedPaths, $excludePatterns, $doxyGenerateMan, $doxygenInputFilter );
-$command = $doxygenBin . ' ' . $generatedConf;
+               $exitcode = 1;
+               system( $command, $exitcode );

 
 

-echo <<<TEXT
+               $this->output( <<<TEXT

 ---------------------------------------------------
 ---------------------------------------------------

-Launching the command:
-
-$command
+Doxygen execution finished.
+Check above for possible errors.

 
 

+You might want to delete the temporary file:
+ $tmpFile

 ---------------------------------------------------
 
 ---------------------------------------------------
 

-TEXT;
-
-$exitcode = 1;
-passthru( $command, $exitcode );
+TEXT
+       );

 
 

-echo <<<TEXT
----------------------------------------------------
-Doxygen execution finished.
-Check above for possible errors.
+               if ( $exitcode !== 0 ) {
+                       $this->error( "Something went wrong (exit: $exitcode)\n",
+                               $exitcode );
+               }

 
 

-You might want to delete the temporary file $generatedConf
+       }

 
 

-TEXT;
+}

 
 

-exit( $exitcode );
+$maintClass = 'MWDocGen';
+require_once RUN_MAINTENANCE_IF_MAIN;