3 * Generate class and file reference documentation for MediaWiki using doxygen.
5 * If the dot DOT language processor is available, attempt call graph
13 * - pass_thru seems to always use buffering (even with ob_implicit_flush()),
14 * that make output slow when doxygen parses language files.
15 * - the menu doesnt work, got disabled at revision 13740. Need to code it.
17 * This program is free software; you can redistribute it and/or modify
18 * it under the terms of the GNU General Public License as published by
19 * the Free Software Foundation; either version 2 of the License, or
20 * (at your option) any later version.
22 * This program is distributed in the hope that it will be useful,
23 * but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 * GNU General Public License for more details.
27 * You should have received a copy of the GNU General Public License along
28 * with this program; if not, write to the Free Software Foundation, Inc.,
29 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
30 * http://www.gnu.org/copyleft/gpl.html
34 * @ingroup Maintenance
36 * @author Antoine Musso <hashar at free dot fr>
37 * @author Brion Vibber
38 * @author Alexandre Emsenhuber
39 * @version first release
43 # Variables / Configuration
46 if ( php_sapi_name() != 'cli' ) {
47 echo 'Run "' . __FILE__
. '" from the command line.';
51 /** Figure out the base directory for MediaWiki location */
52 $mwPath = dirname( __DIR__
) . DIRECTORY_SEPARATOR
;
54 /** doxygen binary script */
55 $doxygenBin = 'doxygen';
57 /** doxygen configuration template for mediawiki */
58 $doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
60 /** doxygen input filter to tweak source file before they are parsed */
61 $doxygenInputFilter = "php {$mwPath}maintenance/mwdoc-filter.php";
63 /** where Phpdoc should output documentation */
64 $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR
;
66 /** MediaWiki subpaths */
67 $mwPathI = $mwPath . 'includes/';
68 $mwPathL = $mwPath . 'languages/';
69 $mwPathM = $mwPath . 'maintenance/';
70 $mwPathS = $mwPath . 'skins/';
72 /** Ignored paths relative to $mwPath */
73 $mwExcludePaths = array(
78 /** Variable to get user input */
80 $excludePatterns = '';
81 /** Whether to generates man pages: */
82 $doxyGenerateMan = false;
88 define( 'MEDIAWIKI', true );
89 require_once( "$mwPath/includes/GlobalFunctions.php" );
92 * Read a line from the shell
93 * @param $prompt String
96 function readaline( $prompt = '' ) {
98 $fp = fopen( "php://stdin", "r" );
99 $resp = trim( fgets( $fp, 1024 ) );
105 * Generate a configuration file given user parameters and return the temporary filename.
106 * @param $doxygenTemplate String: full path for the template.
107 * @param $outputDirectory String: directory where the stuff will be output.
108 * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path).
109 * @param $currentVersion String: Version number of the software
110 * @param $input String: Path to analyze.
111 * @param $exclude String: Additionals path regex to exclude
112 * @param $excludePatterns String: Additionals path regex to exclude
113 * (LocalSettings.php, AdminSettings.php, .svn and .git directories are always excluded)
114 * @param $doxyGenerateMan Boolean
117 function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $input, $exclude, $excludePatterns, $doxyGenerateMan, $doxygenInputFilter ) {
119 $template = file_get_contents( $doxygenTemplate );
120 // Replace template placeholders by correct values.
121 $replacements = array(
122 '{{OUTPUT_DIRECTORY}}' => $outputDirectory,
123 '{{STRIP_FROM_PATH}}' => $stripFromPath,
124 '{{CURRENT_VERSION}}' => $currentVersion,
125 '{{INPUT}}' => $input,
126 '{{EXCLUDE}}' => $exclude,
127 '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
128 '{{HAVE_DOT}}' => `which dot` ?
'YES' : 'NO',
129 '{{GENERATE_MAN}}' => $doxyGenerateMan ?
'YES' : 'NO',
130 '{{INPUT_FILTER}}' => $doxygenInputFilter,
132 $tmpCfg = str_replace( array_keys( $replacements ), array_values( $replacements ), $template );
133 $tmpFileName = tempnam( wfTempDir(), 'mwdocgen-' );
134 file_put_contents( $tmpFileName , $tmpCfg ) or die( "Could not write doxygen configuration to file $tmpFileName\n" );
145 if ( is_array( $argv ) ) {
146 for ($i = 0; $i < count($argv); $i++
) {
147 switch( $argv[$i] ) {
148 case '--all': $input = 0; break;
149 case '--includes': $input = 1; break;
150 case '--languages': $input = 2; break;
151 case '--maintenance': $input = 3; break;
152 case '--skins': $input = 4; break;
156 if ( isset( $argv[$i] ) ) {
160 case '--no-extensions': $input = 6; break;
163 if ( isset( $argv[$i] ) ) {
164 $doxyOutput = realpath( $argv[$i] );
167 case '--generate-man':
168 $doxyGenerateMan = true;
172 Usage: php mwdocgen.php [<command>] [<options>]
175 --all Process entire codebase
176 --includes Process only files in includes/ dir
177 --languages Process only files in languages/ dir
178 --maintenance Process only files in maintenance/ dir
179 --skins Process only files in skins/ dir
180 --file <file> Process only the given file
181 --no-extensions Process everything but extensions directorys
183 If no command is given, you will be prompted.
186 --output <dir> Set output directory (default $doxyOutput)
187 --generate-man Generates man page documentation
188 --help Show this help and exit.
198 // TODO : generate a list of paths ))
200 if ( $input === '' ) {
202 Several documentation possibilities:
203 0 : whole documentation (1 + 2 + 3 + 4)
208 5 : only a given file
209 6 : all but the extensions directory
211 while ( !is_numeric( $input ) )
213 $input = readaline( "\nEnter your choice [0]:" );
214 if ( $input == '' ) {
221 case 0: $input = $mwPath; break;
222 case 1: $input = $mwPathI; break;
223 case 2: $input = $mwPathL; break;
224 case 3: $input = $mwPathM; break;
225 case 4: $input = $mwPathS; break;
227 if ( !isset( $file ) ) {
228 $file = readaline( "Enter file name $mwPath" );
230 $input = $mwPath . $file;
234 $excludePatterns = 'extensions';
237 // @todo FIXME to work on git
240 // Generate path exclusions
241 $excludedPaths = $mwPath . join( " $mwPath", $mwExcludePaths );
242 print "EXCLUDE: $excludedPaths\n\n";
244 $generatedConf = generateConfigFile( $doxygenTemplate, $doxyOutput, $mwPath, $version, $input, $excludedPaths, $excludePatterns, $doxyGenerateMan, $doxygenInputFilter );
245 $command = $doxygenBin . ' ' . $generatedConf;
248 ---------------------------------------------------
249 Launching the command:
253 ---------------------------------------------------
257 passthru( $command );
260 ---------------------------------------------------
261 Doxygen execution finished.
262 Check above for possible errors.
264 You might want to delete the temporary file $generatedConf