maintenance/mwdocgen.php

   1 <?php
   2 /**
   3  * Generate class and file reference documentation for MediaWiki using doxygen.
   4  *
   5  * If the dot DOT language processor is available, attempt call graph
   6  * generation.
   7  *
   8  * Usage:
   9  *   php mwdocgen.php
  10  *
  11  * KNOWN BUGS:
  12  *
  13  * - pass_thru seems to always use buffering (even with ob_implicit_flush()),
  14  * that make output slow when doxygen parses language files.
  15  * - the menu doesnt work, got disabled at revision 13740. Need to code it.
  16  *
  17  * This program is free software; you can redistribute it and/or modify
  18  * it under the terms of the GNU General Public License as published by
  19  * the Free Software Foundation; either version 2 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  25  * GNU General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU General Public License along
  28  * with this program; if not, write to the Free Software Foundation, Inc.,
  29  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  30  * http://www.gnu.org/copyleft/gpl.html
  31  *
  32  * @file
  33  * @todo document
  34  * @ingroup Maintenance
  35  *
  36  * @author Ashar Voultoiz <hashar at free dot fr>
  37  * @author Brion Vibber
  38  * @author Alexandre Emsenhuber
  39  * @version first release
  40  */
  41
  42 #
  43 # Variables / Configuration
  44 #
  45
  46 if ( php_sapi_name() != 'cli' ) {
  47         echo 'Run "' . __FILE__ . '" from the command line.';
  48         die( -1 );
  49 }
  50
  51 /** Figure out the base directory for MediaWiki location */
  52 $mwPath = dirname( dirname( __FILE__ ) ) . DIRECTORY_SEPARATOR;
  53
  54 /** doxygen binary script */
  55 $doxygenBin = 'doxygen';
  56
  57 /** doxygen configuration template for mediawiki */
  58 $doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
  59
  60 /** svnstat command, used to get the version of each file */
  61 $svnstat = $mwPath . 'bin/svnstat';
  62
  63 /** where Phpdoc should output documentation */
  64 $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR ;
  65
  66 /** MediaWiki subpaths */
  67 $mwPathI = $mwPath . 'includes/';
  68 $mwPathL = $mwPath . 'languages/';
  69 $mwPathM = $mwPath . 'maintenance/';
  70 $mwPathS = $mwPath . 'skins/';
  71
  72 /** Ignored paths relative to $mwPath */
  73 $mwExcludePaths = array(
  74         'images',
  75         'static',
  76 );
  77
  78 /** Variable to get user input */
  79 $input = '';
  80 $exclude_patterns = '';
  81
  82 #
  83 # Functions
  84 #
  85
  86 define( 'MEDIAWIKI', true );
  87 require_once( "$mwPath/includes/GlobalFunctions.php" );
  88
  89 /**
  90  * Read a line from the shell
  91  * @param $prompt String
  92  */
  93 function readaline( $prompt = '' ) {
  94         print $prompt;
  95         $fp = fopen( "php://stdin", "r" );
  96         $resp = trim( fgets( $fp, 1024 ) );
  97         fclose( $fp );
  98         return $resp;
  99 }
 100
 101 /**
 102  * Copied from SpecialVersion::getSvnRevision()
 103  * @param $dir String
 104  * @return Mixed: string or false
 105  */
 106 function getSvnRevision( $dir ) {
 107         // http://svnbook.red-bean.com/nightly/en/svn.developer.insidewc.html
 108         $entries = $dir . '/.svn/entries';
 109
 110         if ( !file_exists( $entries ) ) {
 111                 return false;
 112         }
 113
 114         $content = file( $entries );
 115
 116         // check if file is xml (subversion release <= 1.3) or not (subversion release = 1.4)
 117         if ( preg_match( '/^<\?xml/', $content[0] ) ) {
 118                 // subversion is release <= 1.3
 119                 if ( !function_exists( 'simplexml_load_file' ) ) {
 120                         // We could fall back to expat... YUCK
 121                         return false;
 122                 }
 123
 124                 $xml = simplexml_load_file( $entries );
 125
 126                 if ( $xml ) {
 127                         foreach ( $xml->entry as $entry ) {
 128                                 if ( $xml->entry[0]['name'] == '' ) {
 129                                         // The directory entry should always have a revision marker.
 130                                         if ( $entry['revision'] ) {
 131                                                 return intval( $entry['revision'] );
 132                                         }
 133                                 }
 134                         }
 135                 }
 136                 return false;
 137         } else {
 138                 // subversion is release 1.4
 139                 return intval( $content[3] );
 140         }
 141 }
 142
 143 /**
 144  * Generate a configuration file given user parameters and return the temporary filename.
 145  * @param $doxygenTemplate String: full path for the template.
 146  * @param $outputDirectory String: directory where the stuff will be output.
 147  * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path).
 148  * @param $currentVersion String: Version number of the software
 149  * @param $svnstat String: path to the svnstat file
 150  * @param $input String: Path to analyze.
 151  * @param $exclude String: Additionals path regex to exclude
 152  * @param $exclude_patterns String: Additionals path regex to exclude
 153  *                 (LocalSettings.php, AdminSettings.php, .svn and .git directories are always excluded)
 154  */
 155 function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $svnstat, $input, $exclude, $exclude_patterns ) {
 156
 157         $template = file_get_contents( $doxygenTemplate );
 158
 159         // Replace template placeholders by correct values.
 160         $replacements = array(
 161                 '{{OUTPUT_DIRECTORY}}' => $outputDirectory,
 162                 '{{STRIP_FROM_PATH}}'  => $stripFromPath,
 163                 '{{CURRENT_VERSION}}'  => $currentVersion,
 164                 '{{SVNSTAT}}'          => $svnstat,
 165                 '{{INPUT}}'            => $input,
 166                 '{{EXCLUDE}}'          => $exclude,
 167                 '{{EXCLUDE_PATTERNS}}' => $exclude_patterns,
 168                 '{{HAVE_DOT}}'         => `which dot` ? 'YES' : 'NO',
 169         );
 170         $tmpCfg = str_replace( array_keys( $replacements ), array_values( $replacements ), $template );
 171         $tmpFileName = tempnam( wfTempDir(), 'mwdocgen-' );
 172         file_put_contents( $tmpFileName , $tmpCfg ) or die( "Could not write doxygen configuration to file $tmpFileName\n" );
 173
 174         return $tmpFileName;
 175 }
 176
 177 #
 178 # Main !
 179 #
 180
 181 unset( $file );
 182
 183 if ( is_array( $argv ) && isset( $argv[1] ) ) {
 184         switch( $argv[1] ) {
 185         case '--all':         $input = 0; break;
 186         case '--includes':    $input = 1; break;
 187         case '--languages':   $input = 2; break;
 188         case '--maintenance': $input = 3; break;
 189         case '--skins':       $input = 4; break;
 190         case '--file':
 191                 $input = 5;
 192                 if ( isset( $argv[2] ) ) {
 193                         $file = $argv[2];
 194                 }
 195                 break;
 196         case '--no-extensions': $input = 6; break;
 197         }
 198 }
 199
 200 // TODO : generate a list of paths ))
 201
 202 if ( $input === '' ) {
 203         echo <<<OPTIONS
 204 Several documentation possibilities:
 205  0 : whole documentation (1 + 2 + 3 + 4)
 206  1 : only includes
 207  2 : only languages
 208  3 : only maintenance
 209  4 : only skins
 210  5 : only a given file
 211  6 : all but the extensions directory
 212 OPTIONS;
 213         while ( !is_numeric( $input ) )
 214         {
 215                 $input = readaline( "\nEnter your choice [0]:" );
 216                 if ( $input == '' ) {
 217                         $input = 0;
 218                 }
 219         }
 220 }
 221
 222 switch ( $input ) {
 223 case 0: $input = $mwPath;  break;
 224 case 1: $input = $mwPathI; break;
 225 case 2: $input = $mwPathL; break;
 226 case 3: $input = $mwPathM; break;
 227 case 4: $input = $mwPathS; break;
 228 case 5:
 229         if ( !isset( $file ) ) {
 230                 $file = readaline( "Enter file name $mwPath" );
 231         }
 232         $input = $mwPath . $file;
 233 case 6:
 234         $input = $mwPath;
 235         $exclude_patterns = 'extensions';
 236 }
 237
 238 $versionNumber = getSvnRevision( $input );
 239 if ( $versionNumber === false ) { # Not using subversion ?
 240         $svnstat = ''; # Not really useful if subversion not available
 241         # @todo FIXME
 242         $version = 'trunk';
 243 } else {
 244         $version = "trunk (r$versionNumber)";
 245 }
 246
 247 // Generate path exclusions
 248 $excludedPaths = $mwPath . join( " $mwPath", $mwExcludePaths );
 249 print "EXCLUDE: $excludedPaths\n\n";
 250
 251 $generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $version, $svnstat, $input, $excludedPaths, $exclude_patterns );
 252 $command = $doxygenBin . ' ' . $generatedConf;
 253
 254 echo <<<TEXT
 255 ---------------------------------------------------
 256 Launching the command:
 257
 258 $command
 259
 260 ---------------------------------------------------
 261
 262 TEXT;
 263
 264 passthru( $command );
 265
 266 echo <<<TEXT
 267 ---------------------------------------------------
 268 Doxygen execution finished.
 269 Check above for possible errors.
 270
 271 You might want to delete the temporary file $generatedConf
 272
 273 TEXT;