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