[Summary view] [Print] [Text view]

   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 or directory. Multiple values " .
  61              "accepted with comma separation. Path relative to \$IP.",
  62              false, true );
  63          $this->addOption( 'output',
  64              'Path to write doc to',
  65              false, true );
  66          $this->addOption( 'no-extensions',
  67              'Ignore extensions' );
  68      }
  69  
  70  	public function getDbType() {
  71          return Maintenance::DB_NONE;
  72      }
  73  
  74  	protected function init() {
  75          global $IP;
  76  
  77          $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
  78          $this->mwVersion = $this->getOption( 'version', 'master' );
  79  
  80          $this->input = '';
  81          $inputs = explode( ',', $this->getOption( 'file', '' ) );
  82          foreach ( $inputs as $input ) {
  83              # Doxygen inputs are space separted and double quoted
  84              $this->input .= " \"$IP/$input\"";
  85          }
  86  
  87          $this->output = $this->getOption( 'output', "$IP/docs" );
  88  
  89          $this->inputFilter = wfShellWikiCmd(
  90              $IP . '/maintenance/mwdoc-filter.php' );
  91          $this->template = $IP . '/maintenance/Doxyfile';
  92          $this->excludes = array(
  93              'vendor',
  94              'images',
  95              'static',
  96          );
  97          $this->excludePatterns = array();
  98          if ( $this->hasOption( 'no-extensions' ) ) {
  99              $this->excludePatterns[] = 'extensions';
 100          }
 101  
 102          $this->doDot = `which dot`;
 103          $this->doMan = $this->hasOption( 'generate-man' );
 104      }
 105  
 106  	public function execute() {
 107          global $IP;
 108  
 109          $this->init();
 110  
 111          # Build out directories we want to exclude
 112          $exclude = '';
 113          foreach ( $this->excludes as $item ) {
 114              $exclude .= " $IP/$item";
 115          }
 116  
 117          $excludePatterns = implode( ' ', $this->excludePatterns );
 118  
 119          $conf = strtr( file_get_contents( $this->template ),
 120              array(
 121                  '{{OUTPUT_DIRECTORY}}' => $this->output,
 122                  '{{STRIP_FROM_PATH}}' => $IP,
 123                  '{{CURRENT_VERSION}}' => $this->mwVersion,
 124                  '{{INPUT}}' => $this->input,
 125                  '{{EXCLUDE}}' => $exclude,
 126                  '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
 127                  '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
 128                  '{{GENERATE_MAN}}' => $this->doMan ? 'YES' : 'NO',
 129                  '{{INPUT_FILTER}}' => $this->inputFilter,
 130              )
 131          );
 132  
 133          $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
 134          if ( file_put_contents( $tmpFile, $conf ) === false ) {
 135              $this->error( "Could not write doxygen configuration to file $tmpFile\n",
 136                  /** exit code: */ 1 );
 137          }
 138  
 139          $command = $this->doxygen . ' ' . $tmpFile;
 140          $this->output( "Executing command:\n$command\n" );
 141  
 142          $exitcode = 1;
 143          system( $command, $exitcode );
 144  
 145          $this->output( <<<TEXT
 146  ---------------------------------------------------
 147  Doxygen execution finished.
 148  Check above for possible errors.
 149  
 150  You might want to delete the temporary file:
 151   $tmpFile
 152  ---------------------------------------------------
 153  
 154  TEXT
 155          );
 156  
 157          if ( $exitcode !== 0 ) {
 158              $this->error( "Something went wrong (exit: $exitcode)\n",
 159                  $exitcode );
 160          }
 161      }
 162  }
 163  
 164  $maintClass = 'MWDocGen';
 165  require_once RUN_MAINTENANCE_IF_MAIN;