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 Antoine Musso <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( __DIR__ ) . DIRECTORY_SEPARATOR;
  53
  54 /** doxygen binary script */
  55 $doxygenBin = 'doxygen';
  56
  57 /** doxygen configuration template for mediawiki */
  58 $doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
  59
  60 /** doxygen input filter to tweak source file before they are parsed */
  61 $doxygenInputFilter = "php {$mwPath}maintenance/mwdoc-filter.php";
  62
  63 /** svnstat command, used to get the version of each file */
  64 $svnstat = $mwPath . 'bin/svnstat';
  65
  66 /** where Phpdoc should output documentation */
  67 $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR ;
  68
  69 /** MediaWiki subpaths */
  70 $mwPathI = $mwPath . 'includes/';
  71 $mwPathL = $mwPath . 'languages/';
  72 $mwPathM = $mwPath . 'maintenance/';
  73 $mwPathS = $mwPath . 'skins/';
  74
  75 /** Ignored paths relative to $mwPath */
  76 $mwExcludePaths = array(
  77         'images',
  78         'static',
  79 );
  80
  81 /** Variable to get user input */
  82 $input = '';
  83 $excludePatterns = '';
  84 /** Whether to generates man pages: */
  85 $doxyGenerateMan = false;
  86
  87 #
  88 # Functions
  89 #
  90
  91 define( 'MEDIAWIKI', true );
  92 require_once( "$mwPath/includes/GlobalFunctions.php" );
  93
  94 /**
  95  * Read a line from the shell
  96  * @param $prompt String
  97  * @return string
  98  */
  99 function readaline( $prompt = '' ) {
 100         print $prompt;
 101         $fp = fopen( "php://stdin", "r" );
 102         $resp = trim( fgets( $fp, 1024 ) );
 103         fclose( $fp );
 104         return $resp;
 105 }
 106
 107 /**
 108  * Copied from SpecialVersion::getSvnRevision()
 109  * @param $dir String
 110  * @return Mixed: string or false
 111  */
 112 function getSvnRevision( $dir ) {
 113         // http://svnbook.red-bean.com/nightly/en/svn.developer.insidewc.html
 114         $entries = $dir . '/.svn/entries';
 115
 116         if ( !file_exists( $entries ) ) {
 117                 return false;
 118         }
 119
 120         $content = file( $entries );
 121
 122         return intval( $content[3] );
 123 }
 124
 125 /**
 126  * Generate a configuration file given user parameters and return the temporary filename.
 127  * @param $doxygenTemplate String: full path for the template.
 128  * @param $outputDirectory String: directory where the stuff will be output.
 129  * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path).
 130  * @param $currentVersion String: Version number of the software
 131  * @param $svnstat String: path to the svnstat file
 132  * @param $input String: Path to analyze.
 133  * @param $exclude String: Additionals path regex to exclude
 134  * @param $excludePatterns String: Additionals path regex to exclude
 135  *                 (LocalSettings.php, AdminSettings.php, .svn and .git directories are always excluded)
 136  * @param $doxyGenerateMan Boolean
 137  * @return string
 138  */
 139 function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $svnstat, $input, $exclude, $excludePatterns, $doxyGenerateMan ) {
 140         global $doxygenInputFilter;
 141
 142         $template = file_get_contents( $doxygenTemplate );
 143         // Replace template placeholders by correct values.
 144         $replacements = array(
 145                 '{{OUTPUT_DIRECTORY}}' => $outputDirectory,
 146                 '{{STRIP_FROM_PATH}}'  => $stripFromPath,
 147                 '{{CURRENT_VERSION}}'  => $currentVersion,
 148                 '{{SVNSTAT}}'          => $svnstat,
 149                 '{{INPUT}}'            => $input,
 150                 '{{EXCLUDE}}'          => $exclude,
 151                 '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
 152                 '{{HAVE_DOT}}'         => `which dot` ? 'YES' : 'NO',
 153                 '{{GENERATE_MAN}}'     => $doxyGenerateMan ? 'YES' : 'NO',
 154                 '{{INPUT_FILTER}}'     => $doxygenInputFilter,
 155         );
 156         $tmpCfg = str_replace( array_keys( $replacements ), array_values( $replacements ), $template );
 157         $tmpFileName = tempnam( wfTempDir(), 'mwdocgen-' );
 158         file_put_contents( $tmpFileName , $tmpCfg ) or die( "Could not write doxygen configuration to file $tmpFileName\n" );
 159
 160         return $tmpFileName;
 161 }
 162
 163 #
 164 # Main !
 165 #
 166
 167 unset( $file );
 168
 169 if ( is_array( $argv ) ) {
 170         for ($i = 0; $i < count($argv); $i++ ) {
 171                 switch( $argv[$i] ) {
 172                 case '--all':         $input = 0; break;
 173                 case '--includes':    $input = 1; break;
 174                 case '--languages':   $input = 2; break;
 175                 case '--maintenance': $input = 3; break;
 176                 case '--skins':       $input = 4; break;
 177                 case '--file':
 178                         $input = 5;
 179                         $i++;
 180                         if ( isset( $argv[$i] ) ) {
 181                                 $file = $argv[$i];
 182                         }
 183                         break;
 184                 case '--no-extensions': $input = 6; break;
 185                 case '--output':
 186                         $i++;
 187                         if ( isset( $argv[$i] ) ) {
 188                                 $doxyOutput = realpath( $argv[$i] );
 189                         }
 190                         break;
 191                 case '--generate-man':
 192                         $doxyGenerateMan = true;
 193                         break;
 194                 case '--help':
 195                         print <<<END
 196 Usage: php mwdocgen.php [<command>] [<options>]
 197
 198 Commands:
 199     --all           Process entire codebase
 200     --includes      Process only files in includes/ dir
 201     --languages     Process only files in languages/ dir
 202     --maintenance   Process only files in maintenance/ dir
 203     --skins         Process only files in skins/ dir
 204     --file <file>   Process only the given file
 205     --no-extensions Process everything but extensions directorys
 206
 207 If no command is given, you will be prompted.
 208
 209 Other options:
 210     --output <dir>  Set output directory (default $doxyOutput)
 211     --generate-man  Generates man page documentation
 212     --help          Show this help and exit.
 213
 214
 215 END;
 216                         exit(0);
 217                         break;
 218                 }
 219         }
 220 }
 221
 222 // TODO : generate a list of paths ))
 223
 224 if ( $input === '' ) {
 225         echo <<<OPTIONS
 226 Several documentation possibilities:
 227  0 : whole documentation (1 + 2 + 3 + 4)
 228  1 : only includes
 229  2 : only languages
 230  3 : only maintenance
 231  4 : only skins
 232  5 : only a given file
 233  6 : all but the extensions directory
 234 OPTIONS;
 235         while ( !is_numeric( $input ) )
 236         {
 237                 $input = readaline( "\nEnter your choice [0]:" );
 238                 if ( $input == '' ) {
 239                         $input = 0;
 240                 }
 241         }
 242 }
 243
 244 switch ( $input ) {
 245 case 0: $input = $mwPath;  break;
 246 case 1: $input = $mwPathI; break;
 247 case 2: $input = $mwPathL; break;
 248 case 3: $input = $mwPathM; break;
 249 case 4: $input = $mwPathS; break;
 250 case 5:
 251         if ( !isset( $file ) ) {
 252                 $file = readaline( "Enter file name $mwPath" );
 253         }
 254         $input = $mwPath . $file;
 255         break;
 256 case 6:
 257         $input = $mwPath;
 258         $excludePatterns = 'extensions';
 259 }
 260
 261 $versionNumber = getSvnRevision( $input );
 262 if ( $versionNumber === false ) { # Not using subversion ?
 263         $svnstat = ''; # Not really useful if subversion not available
 264         # @todo FIXME
 265         $version = 'trunk';
 266 } else {
 267         $version = "trunk (r$versionNumber)";
 268 }
 269
 270 // Generate path exclusions
 271 $excludedPaths = $mwPath . join( " $mwPath", $mwExcludePaths );
 272 print "EXCLUDE: $excludedPaths\n\n";
 273
 274 $generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $version, $svnstat, $input, $excludedPaths, $excludePatterns, $doxyGenerateMan );
 275 $command = $doxygenBin . ' ' . $generatedConf;
 276
 277 echo <<<TEXT
 278 ---------------------------------------------------
 279 Launching the command:
 280
 281 $command
 282
 283 ---------------------------------------------------
 284
 285 TEXT;
 286
 287 passthru( $command );
 288
 289 echo <<<TEXT
 290 ---------------------------------------------------
 291 Doxygen execution finished.
 292 Check above for possible errors.
 293
 294 You might want to delete the temporary file $generatedConf
 295
 296 TEXT;