MediaWiki  master
mwdocgen.php
Go to the documentation of this file.
1 <?php
37 
38 require_once __DIR__ . '/Maintenance.php';
39 
44 class MWDocGen extends Maintenance {
46  private $doxygen;
48  private $mwVersion;
50  private $output;
52  private $input;
54  private $inputFilter;
56  private $template;
58  private $excludes;
62  private $doDot;
63 
67  public function __construct() {
68  parent::__construct();
69  $this->addDescription( 'Build doxygen documentation' );
70 
71  $this->addOption( 'doxygen',
72  'Path to doxygen',
73  false, true );
74  $this->addOption( 'version',
75  'Pass a MediaWiki version',
76  false, true );
77  $this->addOption( 'file',
78  "Only process given file or directory. Multiple values " .
79  "accepted with comma separation. Path relative to \$IP.",
80  false, true );
81  $this->addOption( 'output',
82  'Path to write doc to',
83  false, true );
84  $this->addOption( 'extensions',
85  'Process the extensions/ directory as well (ignored if --file is used)' );
86  $this->addOption( 'skins',
87  'Process the skins/ directory as well (ignored if --file is used)' );
88  }
89 
90  public function getDbType() {
91  return Maintenance::DB_NONE;
92  }
93 
94  protected function init() {
95  global $wgPhpCli, $IP;
96 
97  $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
98  $this->mwVersion = $this->getOption( 'version', 'master' );
99 
100  $this->input = '';
101  $inputs = explode( ',', $this->getOption( 'file', '' ) );
102  foreach ( $inputs as $input ) {
103  # Doxygen inputs are space separted and double quoted
104  $this->input .= " \"$IP/$input\"";
105  }
106 
107  $this->output = $this->getOption( 'output', "$IP/docs" );
108 
109  // Do not use wfShellWikiCmd, because mwdoc-filter.php is not
110  // a Maintenance script.
111  $this->inputFilter = Shell::escape( [
112  $wgPhpCli,
113  $IP . '/maintenance/mwdoc-filter.php'
114  ] );
115 
116  $this->template = $IP . '/maintenance/Doxyfile';
117  $this->excludes = [
118  'images',
119  'node_modules',
120  'resources',
121  'static',
122  'tests',
123  'vendor',
124  ];
125  $this->excludePatterns = [];
126  if ( $this->input === '' ) {
127  // If no explicit --file filter is set, we're indexing all of $IP,
128  // but any extension or skin submodules should be excluded by default.
129  if ( !$this->hasOption( 'extensions' ) ) {
130  $this->excludePatterns[] = 'extensions';
131  }
132  if ( !$this->hasOption( 'skins' ) ) {
133  $this->excludePatterns[] = 'skins';
134  }
135  }
136 
137  $this->doDot = shell_exec( 'which dot' );
138  }
139 
140  public function execute() {
141  global $IP;
142 
143  $this->init();
144 
145  # Build out directories we want to exclude
146  $exclude = '';
147  foreach ( $this->excludes as $item ) {
148  $exclude .= " $IP/$item";
149  }
150 
151  $excludePatterns = implode( ' ', $this->excludePatterns );
152 
153  $conf = strtr( file_get_contents( $this->template ),
154  [
155  '{{OUTPUT_DIRECTORY}}' => $this->output,
156  '{{STRIP_FROM_PATH}}' => $IP,
157  '{{CURRENT_VERSION}}' => $this->mwVersion,
158  '{{INPUT}}' => $this->input,
159  '{{EXCLUDE}}' => $exclude,
160  '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
161  '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
162  '{{INPUT_FILTER}}' => $this->inputFilter,
163  ]
164  );
165 
166  $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
167  if ( file_put_contents( $tmpFile, $conf ) === false ) {
168  $this->fatalError( "Could not write doxygen configuration to file $tmpFile\n" );
169  }
170 
171  $command = $this->doxygen . ' ' . $tmpFile;
172  $this->output( "Executing command:\n$command\n" );
173 
174  $exitcode = 1;
175  system( $command, $exitcode );
176 
177  $this->output( <<<TEXT
178 ---------------------------------------------------
179 Doxygen execution finished.
180 Check above for possible errors.
181 
182 You might want to delete the temporary file:
183  $tmpFile
184 ---------------------------------------------------
185 
186 TEXT
187  );
188 
189  if ( $exitcode !== 0 ) {
190  $this->fatalError( "Something went wrong (exit: $exitcode)\n", $exitcode );
191  }
192  }
193 }
194 
195 $maintClass = MWDocGen::class;
196 require_once RUN_MAINTENANCE_IF_MAIN;
$wgPhpCli
$wgPhpCli
Executable path of the PHP cli binary.
Definition: DefaultSettings.php:9493
MediaWiki\Shell\Shell
Executes shell commands.
Definition: Shell.php:45
MWDocGen\getDbType
getDbType()
Does the script need different DB access? By default, we give Maintenance scripts normal rights to th...
Definition: mwdocgen.php:90
MWDocGen\$template
string $template
Definition: mwdocgen.php:56
MWDocGen\$excludePatterns
string[] $excludePatterns
Definition: mwdocgen.php:60
Maintenance\fatalError
fatalError( $msg, $exitCode=1)
Output a message and terminate the current script.
Definition: Maintenance.php:489
MWDocGen\$inputFilter
string $inputFilter
Definition: mwdocgen.php:54
Maintenance\addDescription
addDescription( $text)
Set the description text.
Definition: Maintenance.php:329
MWDocGen
Maintenance script that builds doxygen documentation.
Definition: mwdocgen.php:44
Maintenance
Abstract maintenance class for quickly writing and churning out maintenance scripts with minimal effo...
Definition: Maintenance.php:59
MWDocGen\init
init()
Definition: mwdocgen.php:94
MWDocGen\$mwVersion
string $mwVersion
Definition: mwdocgen.php:48
MWDocGen\execute
execute()
Do the actual work.
Definition: mwdocgen.php:140
Maintenance\addOption
addOption( $name, $description, $required=false, $withArg=false, $shortName=false, $multiOccurrence=false)
Add a parameter to the script.
Definition: Maintenance.php:249
MWDocGen\__construct
__construct()
Prepare Maintenance class.
Definition: mwdocgen.php:67
MWDocGen\$output
string $output
Definition: mwdocgen.php:50
MWDocGen\$input
string $input
Definition: mwdocgen.php:52
MWDocGen\$doDot
bool $doDot
Definition: mwdocgen.php:62
Maintenance\DB_NONE
const DB_NONE
Constants for DB access type.
Definition: Maintenance.php:64
$command
$command
Definition: mcc.php:125
wfTempDir
wfTempDir()
Tries to get the system directory for temporary files.
Definition: GlobalFunctions.php:1728
Maintenance\getOption
getOption( $name, $default=null)
Get an option, or return the default.
Definition: Maintenance.php:286
MWDocGen\$doxygen
string $doxygen
Definition: mwdocgen.php:46
Maintenance\output
output( $out, $channel=null)
Throw some output to the user.
Definition: Maintenance.php:435
MWDocGen\$excludes
string[] $excludes
Definition: mwdocgen.php:58
Maintenance\hasOption
hasOption( $name)
Checks to see if a particular option was set.
Definition: Maintenance.php:271
$IP
$IP
Definition: WebStart.php:49
$maintClass
$maintClass
Definition: mwdocgen.php:195