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 <hashar at free dot fr>
25 * @author Brion Vibber
26 * @author Alexandre Emsenhuber
27 * @version first release
31 # Variables / Configuration
34 if ( php_sapi_name() != 'cli' ) {
35 echo 'Run me from the command line.';
39 /** Figure out the base directory for MediaWiki location */
40 $mwPath = dirname( dirname( __FILE__
) ) . DIRECTORY_SEPARATOR
;
42 /** doxygen binary script */
43 $doxygenBin = 'doxygen';
45 /** doxygen configuration template for mediawiki */
46 $doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
48 /** svnstat command, used to get the version of each file */
49 $svnstat = $mwPath . 'bin/svnstat';
51 /** where Phpdoc should output documentation */
52 # $doxyOutput = '/var/www/mwdoc/';
53 $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR
;
55 /** MediaWiki subpaths */
56 $mwPathI = $mwPath . 'includes/';
57 $mwPathL = $mwPath . 'languages/';
58 $mwPathM = $mwPath . 'maintenance/';
59 $mwPathS = $mwPath . 'skins/';
61 /** Variable to get user input */
69 define( 'MEDIAWIKI', true );
70 require_once( "$mwPath/includes/GlobalFunctions.php" );
73 * Read a line from the shell
74 * @param $prompt String
76 function readaline( $prompt = '' ) {
78 $fp = fopen( "php://stdin", "r" );
79 $resp = trim( fgets( $fp, 1024 ) );
85 * Copied from SpecialVersion::getSvnRevision()
87 * @return Mixed: string or false
89 function getSvnRevision( $dir ) {
90 // http://svnbook.red-bean.com/nightly/en/svn.developer.insidewc.html
91 $entries = $dir . '/.svn/entries';
93 if ( !file_exists( $entries ) ) {
97 $content = file( $entries );
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
107 $xml = simplexml_load_file( $entries );
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'] );
121 // subversion is release 1.4
122 return intval( $content[3] );
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 and .svn directories are always excluded)
137 function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $svnstat, $input, $exclude ) {
139 $template = file_get_contents( $doxygenTemplate );
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,
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" );
163 if ( is_array( $argv ) && isset( $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;
172 if ( isset( $argv[2] ) ) {
176 case '--no-extensions': $input = 6; break;
180 // TODO : generate a list of paths ))
182 if ( $input === '' ) {
184 Several documentation possibilities:
185 0 : whole documentation (1 + 2 + 3 + 4)
190 5 : only a given file
191 6 : all but the extensions directory
193 while ( !is_numeric( $input ) )
195 $input = readaline( "\nEnter your choice [0]:" );
196 if ( $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;
209 if ( !isset( $file ) ) {
210 $file = readaline( "Enter file name $mwPath" );
212 $input = $mwPath . $file;
215 $exclude = 'extensions';
218 $versionNumber = getSvnRevision( $input );
219 if ( $versionNumber === false ) { # Not using subversion ?
220 $svnstat = ''; # Not really useful if subversion not available
221 $version = 'trunk'; # FIXME
223 $version = "trunk (r$versionNumber)";
226 $generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $version, $svnstat, $input, $exclude );
227 $command = $doxygenBin . ' ' . $generatedConf;
230 ---------------------------------------------------
231 Launching the command:
235 ---------------------------------------------------
239 passthru( $command );
242 ---------------------------------------------------
243 Doxygen execution finished.
244 Check above for possible errors.
246 You might want to delete the temporary file $generatedConf