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