X-Git-Url: https://git.cyclocoop.org/?a=blobdiff_plain;f=maintenance%2Fmwdocgen.php;h=a353504cb6fb93c41ce9d52e4260aeb35ff6ae1a;hb=d42c2f4d7a689cbab0b90e30f6d2a96d8e32e96e;hp=3b36bad9affd92524d240325b8f9e017c56dd4b3;hpb=7bbe971aec2d548de981a12ed08a7b56a536dcdb;p=lhc%2Fweb%2Fwiklou.git

diff --git a/maintenance/mwdocgen.php b/maintenance/mwdocgen.php
old mode 100755
new mode 100644
index 3b36bad9af..a353504cb6
--- a/maintenance/mwdocgen.php
+++ b/maintenance/mwdocgen.php
@@ -1,20 +1,41 @@
 <?php
 /**
- * Script to easily generate the mediawiki documentation.
+ * Generate class and file reference documentation for MediaWiki using doxygen.
  *
- * By default it will generate the whole documentation but you will be able to
- * generate just some parts.
+ * If the dot DOT language processor is available, attempt call graph
+ * generation.
  *
  * Usage:
  *   php mwdocgen.php
  *
- * Then make a selection from the menu
+ * 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
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
  * @todo document
- * @package MediaWiki
- * @subpackage Maintenance
+ * @ingroup Maintenance
  *
- * @author Ashar Voultoiz <thoane@altern.org>
+ * @author Antoine Musso <hashar at free dot fr>
+ * @author Brion Vibber
+ * @author Alexandre Emsenhuber
  * @version first release
  */
 
@@ -22,145 +43,251 @@
 # Variables / Configuration
 #
 
-if( php_sapi_name() != 'cli' ) {
-	die( "Run me from the command line." );
+if ( php_sapi_name() != 'cli' ) {
+	echo 'Run "' . __FILE__ . '" from the command line.';
+	die( -1 );
 }
 
-/** Phpdoc script with full path */
-#$pdExec	= '/usr/bin/phpdoc';
-$pdExec = 'phpdoc';
+/** Figure out the base directory for MediaWiki location */
+$mwPath = dirname( dirname( __FILE__ ) ) . DIRECTORY_SEPARATOR;
+
+/** doxygen binary script */
+$doxygenBin = 'doxygen';
+
+/** doxygen configuration template for mediawiki */
+$doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
 
-/** Figure out the base directory. */
-$here = dirname( dirname( __FILE__ ) ) . DIRECTORY_SEPARATOR;
+/** svnstat command, used to get the version of each file */
+$svnstat = $mwPath . 'bin/svnstat';
 
 /** where Phpdoc should output documentation */
-#$pdOutput = '/var/www/mwdoc/';
-$pdOutput = "{$here}docs" . DIRECTORY_SEPARATOR . 'html';
-
-/** Some more Phpdoc settings */
-# This will be used as the default for all files that don't have a package,
-# it's useful to set it to something like 'untagged' to hunt down and fix files
-# that don't have a package name declared.
-$pdOthers = " -dn MediaWiki";
-$pdOthers .= ' --title "MediaWiki generated documentation"';
-$pdOthers .= ' --output "HTML:Smarty:HandS"'; #,HTML:Smarty:HandS"'; ###### HTML:frames:DOM/earthli
-$pdOthers .= ' --ignore AdminSettings.php,LocalSettings.php,tests/LocalTestSettings.php';
-$pdOthers .= ' --parseprivate on';
-$pdOthers .= ' --sourcecode on';
-
-/** MediaWiki location */
-#$mwPath = '/var/www/mediawiki/';
-$mwPath = "{$here}";
+$doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR ;
 
 /** MediaWiki subpaths */
-$mwPathI = $mwPath.'includes/';
-$mwPathL = $mwPath.'languages/';
-$mwPathM = $mwPath.'maintenance/';
-$mwPathS = $mwPath.'skins/';
-$mwBaseFiles = $mwPath.'*php ';
+$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 = '';
-/** shell command that will be run */
-$command = '';
+$exclude_patterns = '';
+/** Whether to generates man pages: */
+$wgDoxyGenerateMan = false;
 
 #
 # Functions
 #
 
-function readaline( $prompt = '') {
+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;
+}
+
+/**
+ * Copied from SpecialVersion::getSvnRevision()
+ * @param $dir String
+ * @return Mixed: string or false
+ */
+function getSvnRevision( $dir ) {
+	// http://svnbook.red-bean.com/nightly/en/svn.developer.insidewc.html
+	$entries = $dir . '/.svn/entries';
+
+	if ( !file_exists( $entries ) ) {
+		return false;
 	}
 
+	$content = file( $entries );
+
+	return intval( $content[3] );
+}
+
+/**
+ * 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 $svnstat String: path to the svnstat file
+ * @param $input String: Path to analyze.
+ * @param $exclude String: Additionals path regex to exclude
+ * @param $exclude_patterns String: Additionals path regex to exclude
+ *                 (LocalSettings.php, AdminSettings.php, .svn and .git directories are always excluded)
+ * @return string
+ */
+function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $svnstat, $input, $exclude, $exclude_patterns ) {
+
+	global $wgDoxyGenerateMan;
+
+	$template = file_get_contents( $doxygenTemplate );
+
+	// Replace template placeholders by correct values.
+	$replacements = array(
+		'{{OUTPUT_DIRECTORY}}' => $outputDirectory,
+		'{{STRIP_FROM_PATH}}'  => $stripFromPath,
+		'{{CURRENT_VERSION}}'  => $currentVersion,
+		'{{SVNSTAT}}'          => $svnstat,
+		'{{INPUT}}'            => $input,
+		'{{EXCLUDE}}'          => $exclude,
+		'{{EXCLUDE_PATTERNS}}' => $exclude_patterns,
+		'{{HAVE_DOT}}'         => `which dot` ? 'YES' : 'NO',
+		'{{GENERATE_MAN}}'     => $wgDoxyGenerateMan ? 'YES' : 'NO',
+	);
+	$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 );
 
-if( is_array( $argv ) && isset( $argv[1] ) ) {
-	switch( $argv[1] ) {
-	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;
-		if( isset( $argv[2] ) ) {
-			$file = $argv[2];
+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 '--generate-man':
+			$wgDoxyGenerateMan = true;
+			break;
+		case '--help':
+			print <<<END
+Usage: php mwdocgen.php [<command>] [<options>]
+
+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
+
+If no command is given, you will be prompted.
+
+Other options:
+    --output <dir>  Set output directory (default $doxyOutput)
+    --generate-man  Generates man page documentation
+    --help          Show this help and exit.
+
+
+END;
+			exit(0);
+			break;
 		}
-		break;
 	}
 }
 
-if( $input === '' ) {
-?>Several documentation possibilities:
- 0 : whole documentation (1 + 2 + 3)
+// 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<?php
-	while ( !is_numeric($input) )
+ 5 : only a given file
+ 6 : all but the extensions directory
+OPTIONS;
+	while ( !is_numeric( $input ) )
 	{
 		$input = readaline( "\nEnter your choice [0]:" );
-		if($input == '') {
+		if ( $input == '' ) {
 			$input = 0;
 		}
 	}
 }
 
-$command = 'phpdoc ';
-switch ($input) {
-case 0:
-	$command .= " -f $mwBaseFiles -d $mwPathI,$mwPathL,$mwPathM,$mwPathS";
-	break;
-case 1:
-	$command .= "-d $mwPathI";
-	break;
-case 2:
-	$command .= "-d $mwPathL";
-	break;
-case 3:
-	$command .= "-d $mwPathM";
-	break;
-case 4:
-	$command .= "-d $mwPathS";
-	break;
+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");
+	if ( !isset( $file ) ) {
+		$file = readaline( "Enter file name $mwPath" );
 	}
-	$command .= ' -f '.$mwPath.$file;
+	$input = $mwPath . $file;
+	break;
+case 6:
+	$input = $mwPath;
+	$exclude_patterns = 'extensions';
+}
+
+$versionNumber = getSvnRevision( $input );
+if ( $versionNumber === false ) { # Not using subversion ?
+	$svnstat = ''; # Not really useful if subversion not available
+	# @todo FIXME
+	$version = 'trunk';
+} else {
+	$version = "trunk (r$versionNumber)";
 }
 
-$command .= " -t $pdOutput ".$pdOthers;
+// Generate path exclusions
+$excludedPaths = $mwPath . join( " $mwPath", $mwExcludePaths );
+print "EXCLUDE: $excludedPaths\n\n";
 
-?>
+$generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $version, $svnstat, $input, $excludedPaths, $exclude_patterns );
+$command = $doxygenBin . ' ' . $generatedConf;
+
+echo <<<TEXT
 ---------------------------------------------------
 Launching the command:
 
-<?php echo $command ?>
+$command
 
 ---------------------------------------------------
-<?php
 
-passthru($command);
+TEXT;
+
+passthru( $command );
 
-?>
+echo <<<TEXT
 ---------------------------------------------------
-Phpdoc execution finished.
+Doxygen execution finished.
 Check above for possible errors.
-<?php
-
-# phpdoc -d ./mediawiki/includes/ ./mediawiki/maintenance/ -f ./mediawiki/*php -t ./mwdoc/ -dn 'MediaWiki' --title 'MediaWiki generated documentation' -o 'HTML:frames:DOM/earthli'
 
-# phpdoc -f ./mediawiki/includes/GlobalFunctions.php -t ./mwdoc/ -dn 'MediaWiki' --title 'MediaWiki generated documentation' -o 'HTML:frames:DOM/earthli'
+You might want to delete the temporary file $generatedConf
 
-?>
+TEXT;