<?php
/**
- * Script to easily generate the mediawiki documentation using doxygen.
+ * Generate class and file reference documentation for MediaWiki using doxygen.
*
- * By default it will generate the whole documentation but you will be able to
- * generate just some parts.
+ * If the dot DOT language processor is available, attempt call graph
+ * generation.
*
* Usage:
* php mwdocgen.php
*
- * Then make a selection from the menu
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
*
- * KNOWN BUGS:
- *
- * - pass_thru seems to always use buffering (even with ob_implicit_flush()),
- * that make output slow when doxygen parses language files.
- * - the menu doesnt work, got disabled at revision 13740. Need to code it.
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
*
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
*
+ * @file
* @todo document
- * @addtogroup Maintenance
+ * @ingroup Maintenance
*
- * @author Ashar Voultoiz <thoane@altern.org>
+ * @author Antoine Musso <hashar at free dot fr>
+ * @author Brion Vibber
+ * @author Alexandre Emsenhuber
* @version first release
*/
-#
-# Variables / Configuration
-#
-
-if( php_sapi_name() != 'cli' ) {
- echo 'Run me from the command line.';
- die( -1 );
-}
-
-/** Figure out the base directory for MediaWiki location */
-$mwPath = dirname( dirname( __FILE__ ) ) . DIRECTORY_SEPARATOR;
-
-/** Global variable: temporary directory */
-$tmpPath = '/tmp/';
-
-/** doxygen binary script */
-$doxygenBin = 'doxygen';
-
-/** doxygen configuration template for mediawiki */
-$doxygenTemplate = $mwPath . 'maintenance/Doxyfile';
-
-/** where Phpdoc should output documentation */
-#$doxyOutput = '/var/www/mwdoc/';
-$doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR ;
-
-/** MediaWiki subpaths */
-$mwPathI = $mwPath.'includes/';
-$mwPathL = $mwPath.'languages/';
-$mwPathM = $mwPath.'maintenance/';
-$mwPathS = $mwPath.'skins/';
-
-/** Variable to get user input */
-$input = '';
+require_once __DIR__ . '/Maintenance.php';
-/** shell command that will be run */
-$command = $doxygenBin;
-
-#
-# Functions
-#
+/**
+ * Maintenance script that builds doxygen documentation.
+ * @ingroup Maintenance
+ */
+class MWDocGen extends Maintenance {
+
+ /**
+ * Prepare Maintenance class
+ */
+ public function __construct() {
+ parent::__construct();
+ $this->addDescription( 'Build doxygen documentation' );
+
+ $this->addOption( 'doxygen',
+ 'Path to doxygen',
+ false, true );
+ $this->addOption( 'version',
+ 'Pass a MediaWiki version',
+ false, true );
+ $this->addOption( 'generate-man',
+ 'Whether to generate man files' );
+ $this->addOption( 'file',
+ "Only process given file or directory. Multiple values " .
+ "accepted with comma separation. Path relative to \$IP.",
+ false, true );
+ $this->addOption( 'output',
+ 'Path to write doc to',
+ false, true );
+ $this->addOption( 'no-extensions',
+ 'Ignore extensions' );
+ }
-function readaline( $prompt = '') {
- print $prompt;
- $fp = fopen( "php://stdin", "r" );
- $resp = trim( fgets( $fp, 1024 ) );
- fclose( $fp );
- return $resp;
+ public function getDbType() {
+ return Maintenance::DB_NONE;
}
-/**
- * Generate a configuration file given user parameters and return the temporary filename.
- * @param $doxygenTemplate String: full path for the template.
- * @param $outputDirectory String: directory where the stuff will be output.
- * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path).
- * @param $input String: Path to analyze.
- */
-function generateConfigFile($doxygenTemplate, $outputDirectory, $stripFromPath, $input) {
- global $tmpPath ;
-
- $template = file_get_contents($doxygenTemplate);
-
- // Replace template placeholders by correct values.
- $tmpCfg = str_replace(
- array(
- '{{OUTPUT_DIRECTORY}}',
- '{{STRIP_FROM_PATH}}',
- '{{INPUT}}',
- ),
- array(
- $outputDirectory,
- $stripFromPath,
- $input,
- ),
- $template
- );
- $tmpFileName = $tmpPath . 'mwdocgen'. rand() .'.tmp';
- file_put_contents( $tmpFileName , $tmpCfg ) or die("Could not write doxygen configuration to file $tmpFileName\n");
+ protected function init() {
+ global $wgPhpCli, $IP;
- return $tmpFileName;
-}
+ $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
+ $this->mwVersion = $this->getOption( 'version', 'master' );
-#
-# Main !
-#
-
-unset( $file );
-
-if( is_array( $argv ) && isset( $argv[1] ) ) {
- switch( $argv[1] ) {
- case '--all': $input = 0; break;
- case '--includes': $input = 1; break;
- case '--languages': $input = 2; break;
- case '--maintenance': $input = 3; break;
- case '--skins': $input = 4; break;
- case '--file':
- $input = 5;
- if( isset( $argv[2] ) ) {
- $file = $argv[2];
+ $this->input = '';
+ $inputs = explode( ',', $this->getOption( 'file', '' ) );
+ foreach ( $inputs as $input ) {
+ # Doxygen inputs are space separted and double quoted
+ $this->input .= " \"$IP/$input\"";
}
- break;
- }
-}
-if( $input === '' ) {
-?>Several documentation possibilities:
- 0 : whole documentation (1 + 2 + 3 + 4)
- 1 : only includes
- 2 : only languages
- 3 : only maintenance
- 4 : only skins
- 5 : only a given file<?php
- while ( !is_numeric($input) )
- {
- $input = readaline( "\nEnter your choice [0]:" );
- if($input == '') {
- $input = 0;
+ $this->output = $this->getOption( 'output', "$IP/docs" );
+
+ // Do not use wfShellWikiCmd, because mwdoc-filter.php is not
+ // a Maintenance script.
+ $this->inputFilter = wfEscapeShellArg( [
+ $wgPhpCli,
+ $IP . '/maintenance/mwdoc-filter.php'
+ ] );
+
+ $this->template = $IP . '/maintenance/Doxyfile';
+ $this->excludes = [
+ 'vendor',
+ 'node_modules',
+ 'images',
+ 'static',
+ ];
+ $this->excludePatterns = [];
+ if ( $this->hasOption( 'no-extensions' ) ) {
+ $this->excludePatterns[] = 'extensions';
}
+
+ $this->doDot = shell_exec( 'which dot' );
+ $this->doMan = $this->hasOption( 'generate-man' );
}
-}
-/*
-switch ($input) {
-case 0:
- $command .= " -f $mwBaseFiles -d $mwPathI,$mwPathL,$mwPathM,$mwPathS";
- break;
-case 1:
- $command .= "-d $mwPathI";
- break;
-case 2:
- $command .= "-d $mwPathL";
- break;
-case 3:
- $command .= "-d $mwPathM";
- break;
-case 4:
- $command .= "-d $mwPathS";
- break;
-case 5:
- if( !isset( $file ) ) {
- $file = readaline("Enter file name $mwPath");
- }
- $command .= ' -f '.$mwPath.$file;
-}
-$command .= " -t $pdOutput ".$pdOthers;
+ public function execute() {
+ global $IP;
-*/
+ $this->init();
-// TODO : generate a list of paths ))
-$input = $mwPath;
+ # Build out directories we want to exclude
+ $exclude = '';
+ foreach ( $this->excludes as $item ) {
+ $exclude .= " $IP/$item";
+ }
-$generatedConf = generateConfigFile($doxygenTemplate, $doxyOutput, $mwPath, $input );
-$command = $doxygenBin . ' ' . $generatedConf ;
+ $excludePatterns = implode( ' ', $this->excludePatterns );
+
+ $conf = strtr( file_get_contents( $this->template ),
+ [
+ '{{OUTPUT_DIRECTORY}}' => $this->output,
+ '{{STRIP_FROM_PATH}}' => $IP,
+ '{{CURRENT_VERSION}}' => $this->mwVersion,
+ '{{INPUT}}' => $this->input,
+ '{{EXCLUDE}}' => $exclude,
+ '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
+ '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
+ '{{GENERATE_MAN}}' => $this->doMan ? 'YES' : 'NO',
+ '{{INPUT_FILTER}}' => $this->inputFilter,
+ ]
+ );
-?>
----------------------------------------------------
-Launching the command:
+ $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
+ if ( file_put_contents( $tmpFile, $conf ) === false ) {
+ $this->error( "Could not write doxygen configuration to file $tmpFile\n",
+ /** exit code: */ 1 );
+ }
-<?php echo $command ?>
+ $command = $this->doxygen . ' ' . $tmpFile;
+ $this->output( "Executing command:\n$command\n" );
----------------------------------------------------
-<?php
-
-passthru($command);
+ $exitcode = 1;
+ system( $command, $exitcode );
-?>
+ $this->output( <<<TEXT
---------------------------------------------------
Doxygen execution finished.
Check above for possible errors.
-You might want to deleted the temporary file <?php echo $generatedConf; ?>
-
-<?php
+You might want to delete the temporary file:
+ $tmpFile
+---------------------------------------------------
-# phpdoc -d ./mediawiki/includes/ ./mediawiki/maintenance/ -f ./mediawiki/*php -t ./mwdoc/ -dn 'MediaWiki' --title 'MediaWiki generated documentation' -o 'HTML:frames:DOM/earthli'
+TEXT
+ );
-# phpdoc -f ./mediawiki/includes/GlobalFunctions.php -t ./mwdoc/ -dn 'MediaWiki' --title 'MediaWiki generated documentation' -o 'HTML:frames:DOM/earthli'
+ if ( $exitcode !== 0 ) {
+ $this->error( "Something went wrong (exit: $exitcode)\n",
+ $exitcode );
+ }
+ }
+}
-?>
+$maintClass = 'MWDocGen';
+require_once RUN_MAINTENANCE_IF_MAIN;
scripts.mit.edu / autoinstallsdev / mediawiki.git / blobdiff