maintenance/mwdocgen.php

   1 <?php
   2 /**
   3  * Generate class and file reference documentation for MediaWiki using doxygen.
   4  *
   5  * If the dot DOT language processor is available, attempt call graph
   6  * generation.
   7  *
   8  * Usage:
   9  *   php mwdocgen.php
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License along
  22  * with this program; if not, write to the Free Software Foundation, Inc.,
  23  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  24  * http://www.gnu.org/copyleft/gpl.html
  25  *
  26  * @file
  27  * @todo document
  28  * @ingroup Maintenance
  29  *
  30  * @author Antoine Musso <hashar at free dot fr>
  31  * @author Brion Vibber
  32  * @author Alexandre Emsenhuber
  33  * @version first release
  34  */
  35
  36 require_once __DIR__ . '/Maintenance.php';
  37
  38 /**
  39  * Maintenance script that builds doxygen documentation.
  40  * @ingroup Maintenance
  41  */
  42 class MWDocGen extends Maintenance {
  43
  44         /**
  45          * Prepare Maintenance class
  46          */
  47         public function __construct() {
  48                 parent::__construct();
  49                 $this->mDescription = 'Build doxygen documentation';
  50
  51                 $this->addOption( 'doxygen',
  52                         'Path to doxygen',
  53                         false, true );
  54                 $this->addOption( 'version',
  55                         'Pass a MediaWiki version',
  56                         false, true );
  57                 $this->addOption( 'generate-man',
  58                         'Whether to generate man files' );
  59                 $this->addOption( 'file',
  60                         'Only process given file (relative to $IP)',
  61                         false, true );
  62                 $this->addOption( 'output',
  63                         'Path to write doc to',
  64                         false, true );
  65                 $this->addOption( 'no-extensions',
  66                         'Ignore extensions' );
  67         }
  68
  69         public function getDbType() {
  70                 return Maintenance::DB_NONE;
  71         }
  72
  73         protected function init() {
  74                 global $IP;
  75
  76                 $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
  77                 $this->mwVersion = $this->getOption( 'version', 'master' );
  78                 $this->input = $IP . '/' . $this->getOption( 'file', '' );
  79                 $this->output = $this->getOption( 'output', "$IP/docs" );
  80
  81                 $this->inputFilter = wfShellWikiCmd(
  82                         $IP . '/maintenance/mwdoc-filter.php' );
  83                 $this->template = $IP . '/maintenance/Doxyfile';
  84                 $this->excludes = array(
  85                         'images',
  86                         'static',
  87                 );
  88                 $this->excludePatterns = array();
  89                 if ( $this->hasOption( 'no-extensions' ) ) {
  90                         $this->excludePatterns[] = 'extensions';
  91                 }
  92
  93                 $this->doDot = `which dot`;
  94                 $this->doMan = $this->hasOption( 'generate-man' );
  95         }
  96
  97         public function execute() {
  98                 global $IP;
  99
 100                 $this->init();
 101
 102                 # Build out directories we want to exclude
 103                 $exclude = '';
 104                 foreach ( $this->excludes as $item ) {
 105                         $exclude .= " $IP/$item";
 106                 }
 107
 108                 $excludePatterns = implode( ' ', $this->excludePatterns );
 109
 110                 $conf = strtr( file_get_contents( $this->template ),
 111                         array(
 112                                 '{{OUTPUT_DIRECTORY}}' => $this->output,
 113                                 '{{STRIP_FROM_PATH}}' => $IP,
 114                                 '{{CURRENT_VERSION}}' => $this->mwVersion,
 115                                 '{{INPUT}}' => $this->input,
 116                                 '{{EXCLUDE}}' => $exclude,
 117                                 '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
 118                                 '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
 119                                 '{{GENERATE_MAN}}' => $this->doMan ? 'YES' : 'NO',
 120                                 '{{INPUT_FILTER}}' => $this->inputFilter,
 121                         )
 122                 );
 123
 124                 $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
 125                 if ( file_put_contents( $tmpFile, $conf ) === false ) {
 126                         $this->error( "Could not write doxygen configuration to file $tmpFile\n",
 127                                 /** exit code: */ 1 );
 128                 }
 129
 130                 $command = $this->doxygen . ' ' . $tmpFile;
 131                 $this->output( "Executing command:\n$command\n" );
 132
 133                 $exitcode = 1;
 134                 system( $command, $exitcode );
 135
 136                 $this->output( <<<TEXT
 137 ---------------------------------------------------
 138 Doxygen execution finished.
 139 Check above for possible errors.
 140
 141 You might want to delete the temporary file:
 142  $tmpFile
 143 ---------------------------------------------------
 144
 145 TEXT
 146         );
 147
 148                 if ( $exitcode !== 0 ) {
 149                         $this->error( "Something went wrong (exit: $exitcode)\n",
 150                                 $exitcode );
 151                 }
 152
 153         }
 154
 155 }
 156
 157 $maintClass = 'MWDocGen';
 158 require_once RUN_MAINTENANCE_IF_MAIN;