maintenance/mwdocgen.php

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