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