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 /** where Phpdoc should output documentation */
  50 #$doxyOutput = '/var/www/mwdoc/';
  51 $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR ;
  52
  53 /** MediaWiki subpaths */
  54 $mwPathI = $mwPath.'includes/';
  55 $mwPathL = $mwPath.'languages/';
  56 $mwPathM = $mwPath.'maintenance/';
  57 $mwPathS = $mwPath.'skins/';
  58
  59 /** Variable to get user input */
  60 $input = '';
  61
  62 /** shell command that will be run */
  63 $command = $doxygenBin;
  64
  65 #
  66 # Functions
  67 #
  68
  69 function readaline( $prompt = '') {
  70         print $prompt;
  71         $fp = fopen( "php://stdin", "r" );
  72         $resp = trim( fgets( $fp, 1024 ) );
  73         fclose( $fp );
  74         return $resp;
  75         }
  76
  77 /**
  78  * Generate a configuration file given user parameters and return the temporary filename.
  79  * @param $doxygenTemplate String: full path for the template.
  80  * @param $outputDirectory String: directory where the stuff will be output.
  81  * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path).
  82  * @param $input String: Path to analyze.
  83  */
  84 function generateConfigFile($doxygenTemplate, $outputDirectory, $stripFromPath, $input) {
  85         global $tmpPath ;
  86
  87         $template = file_get_contents($doxygenTemplate);
  88
  89         // Replace template placeholders by correct values.
  90         $tmpCfg = str_replace(
  91                         array(
  92                                 '{{OUTPUT_DIRECTORY}}',
  93                                 '{{STRIP_FROM_PATH}}',
  94                                 '{{INPUT}}',
  95                         ),
  96                         array(
  97                                 $outputDirectory,
  98                                 $stripFromPath,
  99                                 $input,
 100                         ),
 101                         $template
 102                 );
 103         $tmpFileName = $tmpPath . 'mwdocgen'. rand() .'.tmp';
 104         file_put_contents( $tmpFileName , $tmpCfg ) or die("Could not write doxygen configuration to file $tmpFileName\n");
 105
 106         return $tmpFileName;
 107 }
 108
 109 #
 110 # Main !
 111 #
 112
 113 unset( $file );
 114
 115 if( is_array( $argv ) && isset( $argv[1] ) ) {
 116         switch( $argv[1] ) {
 117         case '--all':         $input = 0; break;
 118         case '--includes':    $input = 1; break;
 119         case '--languages':   $input = 2; break;
 120         case '--maintenance': $input = 3; break;
 121         case '--skins':       $input = 4; break;
 122         case '--file':
 123                 $input = 5;
 124                 if( isset( $argv[2] ) ) {
 125                         $file = $argv[2];
 126                 }
 127                 break;
 128         }
 129 }
 130
 131 if( $input === '' ) {
 132 ?>Several documentation possibilities:
 133  0 : whole documentation (1 + 2 + 3 + 4)
 134  1 : only includes
 135  2 : only languages
 136  3 : only maintenance
 137  4 : only skins
 138  5 : only a given file<?php
 139         while ( !is_numeric($input) )
 140         {
 141                 $input = readaline( "\nEnter your choice [0]:" );
 142                 if($input == '') {
 143                         $input = 0;
 144                 }
 145         }
 146 }
 147 /*
 148 switch ($input) {
 149 case 0:
 150         $command .= " -f $mwBaseFiles -d $mwPathI,$mwPathL,$mwPathM,$mwPathS";
 151         break;
 152 case 1:
 153         $command .= "-d $mwPathI";
 154         break;
 155 case 2:
 156         $command .= "-d $mwPathL";
 157         break;
 158 case 3:
 159         $command .= "-d $mwPathM";
 160         break;
 161 case 4:
 162         $command .= "-d $mwPathS";
 163         break;
 164 case 5:
 165         if( !isset( $file ) ) {
 166                 $file = readaline("Enter file name $mwPath");
 167         }
 168         $command .= ' -f '.$mwPath.$file;
 169 }
 170
 171 $command .= " -t $pdOutput ".$pdOthers;
 172
 173 */
 174
 175 // TODO : generate a list of paths ))
 176 $input = $mwPath;
 177
 178 $generatedConf = generateConfigFile($doxygenTemplate, $doxyOutput, $mwPath, $input );
 179 $command = $doxygenBin . ' ' . $generatedConf ;
 180
 181 ?>
 182 ---------------------------------------------------
 183 Launching the command:
 184
 185 <?php echo $command ?>
 186
 187 ---------------------------------------------------
 188 <?php
 189
 190 passthru($command);
 191
 192 ?>
 193 ---------------------------------------------------
 194 Doxygen execution finished.
 195 Check above for possible errors.
 196
 197 You might want to deleted the temporary file <?php echo $generatedConf; ?>
 198
 199 <?php
 200
 201 # phpdoc -d ./mediawiki/includes/ ./mediawiki/maintenance/ -f ./mediawiki/*php -t ./mwdoc/ -dn 'MediaWiki' --title 'MediaWiki generated documentation' -o 'HTML:frames:DOM/earthli'
 202
 203 # phpdoc -f ./mediawiki/includes/GlobalFunctions.php -t ./mwdoc/ -dn 'MediaWiki' --title 'MediaWiki generated documentation' -o 'HTML:frames:DOM/earthli'
 204
 205 ?>