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