3 * Script to easily generate the mediawiki documentation using doxygen.
5 * By default it will generate the whole documentation but you will be able to
6 * generate just some parts.
11 * Then make a selection from the menu
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.
22 * @ingroup Maintenance
24 * @author Ashar Voultoiz <thoane@altern.org>
25 * @version first release
29 # Variables / Configuration
32 if( php_sapi_name() != 'cli' ) {
33 echo 'Run me from the command line.';
37 /** Figure out the base directory for MediaWiki location */
38 $mwPath = dirname( dirname( __FILE__
) ) . DIRECTORY_SEPARATOR
;
40 /** Global variable: temporary directory */
43 /** doxygen binary script */
44 $doxygenBin = 'doxygen';
46 /** doxygen configuration template for mediawiki */
47 $doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
49 /** svnstat command, used to get the version of each file */
50 $svnstat = $mwPath . 'bin/svnstat';
52 /** where Phpdoc should output documentation */
53 #$doxyOutput = '/var/www/mwdoc/';
54 $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR
;
56 /** MediaWiki subpaths */
57 $mwPathI = $mwPath.'includes/';
58 $mwPathL = $mwPath.'languages/';
59 $mwPathM = $mwPath.'maintenance/';
60 $mwPathS = $mwPath.'skins/';
62 /** Variable to get user input */
71 * Read a line from the shell
72 * @param $prompt String
74 function readaline( $prompt = '' ){
76 $fp = fopen( "php://stdin", "r" );
77 $resp = trim( fgets( $fp, 1024 ) );
83 * Copied from SpecialVersion::getSvnRevision()
85 * @return Mixed: string or false
87 function getSvnRevision( $dir ) {
88 // http://svnbook.red-bean.com/nightly/en/svn.developer.insidewc.html
89 $entries = $dir . '/.svn/entries';
91 if( !file_exists( $entries ) ) {
95 $content = file( $entries );
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
105 $xml = simplexml_load_file( $entries );
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'] );
119 // subversion is release 1.4
120 return intval( $content[3] );
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)
135 function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $svnstat, $input, $exclude ){
138 $template = file_get_contents( $doxygenTemplate );
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,
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");
162 if( is_array( $argv ) && isset( $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;
171 if( isset( $argv[2] ) ) {
175 case '--no-extensions': $input = 6; break;
179 // TODO : generate a list of paths ))
181 if( $input === '' ) {
183 Several documentation possibilities:
184 0 : whole documentation (1 + 2 + 3 + 4)
189 5 : only a given file
190 6 : all but the extensions directory
192 while ( !is_numeric($input) )
194 $input = readaline( "\nEnter your choice [0]:" );
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;
208 if( !isset( $file ) ) {
209 $file = readaline( "Enter file name $mwPath" );
211 $input = $mwPath.$file;
214 $exclude = 'extensions';
217 $versionNumber = getSvnRevision( $input );
218 if( $versionNumber === false ){ #Not using subversion ?
219 $svnstat = ''; # Not really useful if subversion not available
220 $version = 'trunk'; # FIXME
222 $version = "trunk (r$versionNumber)";
225 $generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $version, $svnstat, $input, $exclude );
226 $command = $doxygenBin . ' ' . $generatedConf;
229 ---------------------------------------------------
230 Launching the command:
234 ---------------------------------------------------
238 passthru( $command );
241 ---------------------------------------------------
242 Doxygen execution finished.
243 Check above for possible errors.
245 You might want to delete the temporary file $generatedConf