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 use MediaWiki\Shell\Shell;
  37
  38 require_once __DIR__ . '/Maintenance.php';
  39
  40 /**
  41  * Maintenance script that builds doxygen documentation.
  42  * @ingroup Maintenance
  43  */
  44 class MWDocGen extends Maintenance {
  45         /** @var string */
  46         private $doxygen;
  47         /** @var string */
  48         private $mwVersion;
  49         /** @var string */
  50         private $output;
  51         /** @var string */
  52         private $input;
  53         /** @var string */
  54         private $inputFilter;
  55         /** @var string */
  56         private $template;
  57         /** @var string[] */
  58         private $excludes;
  59         /** @var string[] */
  60         private $excludePatterns;
  61         /** @var bool */
  62         private $doDot;
  63         /** @var bool */
  64         private $doMan;
  65
  66         /**
  67          * Prepare Maintenance class
  68          */
  69         public function __construct() {
  70                 parent::__construct();
  71                 $this->addDescription( 'Build doxygen documentation' );
  72
  73                 $this->addOption( 'doxygen',
  74                         'Path to doxygen',
  75                         false, true );
  76                 $this->addOption( 'version',
  77                         'Pass a MediaWiki version',
  78                         false, true );
  79                 $this->addOption( 'file',
  80                         "Only process given file or directory. Multiple values " .
  81                         "accepted with comma separation. Path relative to \$IP.",
  82                         false, true );
  83                 $this->addOption( 'output',
  84                         'Path to write doc to',
  85                         false, true );
  86                 $this->addOption( 'extensions',
  87                         'Process the extensions/ directory as well (ignored if --file is used)' );
  88                 $this->addOption( 'skins',
  89                         'Process the skins/ directory as well (ignored if --file is used)' );
  90         }
  91
  92         public function getDbType() {
  93                 return Maintenance::DB_NONE;
  94         }
  95
  96         protected function init() {
  97                 global $wgPhpCli, $IP;
  98
  99                 $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
 100                 $this->mwVersion = $this->getOption( 'version', 'master' );
 101
 102                 $this->input = '';
 103                 $inputs = explode( ',', $this->getOption( 'file', '' ) );
 104                 foreach ( $inputs as $input ) {
 105                         # Doxygen inputs are space separted and double quoted
 106                         $this->input .= " \"$IP/$input\"";
 107                 }
 108
 109                 $this->output = $this->getOption( 'output', "$IP/docs" );
 110
 111                 // Do not use wfShellWikiCmd, because mwdoc-filter.php is not
 112                 // a Maintenance script.
 113                 $this->inputFilter = Shell::escape( [
 114                         $wgPhpCli,
 115                         $IP . '/maintenance/mwdoc-filter.php'
 116                 ] );
 117
 118                 $this->template = $IP . '/maintenance/Doxyfile';
 119                 $this->excludes = [
 120                         'images',
 121                         'node_modules',
 122                         'resources',
 123                         'static',
 124                         'tests',
 125                         'vendor',
 126                 ];
 127                 $this->excludePatterns = [];
 128                 if ( $this->input === '' ) {
 129                         // If no explicit --file filter is set, we're indexing all of $IP,
 130                         // but any extension or skin submodules should be excluded by default.
 131                         if ( !$this->hasOption( 'extensions' ) ) {
 132                                 $this->excludePatterns[] = 'extensions';
 133                         }
 134                         if ( !$this->hasOption( 'skins' ) ) {
 135                                 $this->excludePatterns[] = 'skins';
 136                         }
 137                 }
 138
 139                 $this->doDot = shell_exec( 'which dot' );
 140         }
 141
 142         public function execute() {
 143                 global $IP;
 144
 145                 $this->init();
 146
 147                 # Build out directories we want to exclude
 148                 $exclude = '';
 149                 foreach ( $this->excludes as $item ) {
 150                         $exclude .= " $IP/$item";
 151                 }
 152
 153                 $excludePatterns = implode( ' ', $this->excludePatterns );
 154
 155                 $conf = strtr( file_get_contents( $this->template ),
 156                         [
 157                                 '{{OUTPUT_DIRECTORY}}' => $this->output,
 158                                 '{{STRIP_FROM_PATH}}' => $IP,
 159                                 '{{CURRENT_VERSION}}' => $this->mwVersion,
 160                                 '{{INPUT}}' => $this->input,
 161                                 '{{EXCLUDE}}' => $exclude,
 162                                 '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
 163                                 '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
 164                                 '{{INPUT_FILTER}}' => $this->inputFilter,
 165                         ]
 166                 );
 167
 168                 $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
 169                 if ( file_put_contents( $tmpFile, $conf ) === false ) {
 170                         $this->fatalError( "Could not write doxygen configuration to file $tmpFile\n" );
 171                 }
 172
 173                 $command = $this->doxygen . ' ' . $tmpFile;
 174                 $this->output( "Executing command:\n$command\n" );
 175
 176                 $exitcode = 1;
 177                 system( $command, $exitcode );
 178
 179                 $this->output( <<<TEXT
 180 ---------------------------------------------------
 181 Doxygen execution finished.
 182 Check above for possible errors.
 183
 184 You might want to delete the temporary file:
 185  $tmpFile
 186 ---------------------------------------------------
 187
 188 TEXT
 189                 );
 190
 191                 if ( $exitcode !== 0 ) {
 192                         $this->fatalError( "Something went wrong (exit: $exitcode)\n", $exitcode );
 193                 }
 194         }
 195 }
 196
 197 $maintClass = MWDocGen::class;
 198 require_once RUN_MAINTENANCE_IF_MAIN;