MediaWiki master
mwdocgen.php
Go to the documentation of this file.
1<?php
38
39// @codeCoverageIgnoreStart
40require_once __DIR__ . '/Maintenance.php';
41// @codeCoverageIgnoreEnd
42
47class MWDocGen extends Maintenance {
49 private $doxygen;
51 private $mwVersion;
53 private $output;
55 private $input;
57 private $inputFilter;
59 private $template;
61 private $excludes;
63 private $doDot;
64
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
92 public function getDbType() {
93 return Maintenance::DB_NONE;
94 }
95
96 protected function init() {
97 global $wgPhpCli;
98
99 $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
100 $this->mwVersion = $this->getOption( 'version', 'master' );
101
102 $this->output = $this->getOption( 'output', 'docs' );
103
104 // Do not use wfShellWikiCmd, because mwdoc-filter.php is not
105 // a Maintenance script.
106 $this->inputFilter = Shell::escape( [
107 $wgPhpCli,
108 MW_INSTALL_PATH . '/maintenance/mwdoc-filter.php'
109 ] );
110
111 $this->template = MW_INSTALL_PATH . '/maintenance/Doxyfile';
112 $this->excludes = [
113 'cache',
114 'images',
115 ];
116
117 $file = $this->getOption( 'file' );
118 if ( $file !== null ) {
119 $this->input = '';
120 foreach ( explode( ',', $file ) as $input ) {
121 // Doxygen inputs are space separated and double quoted
122 $this->input .= " \"$input\"";
123 }
124 } else {
125 // If no explicit --file filter is set, we're indexing all of MediaWiki core
126 // in MW_INSTALL_PATH, but not extension and skin submodules (T317451).
127 $this->input = '';
128 if ( !$this->hasOption( 'extensions' ) ) {
129 $this->excludes[] = 'extensions';
130 }
131 if ( !$this->hasOption( 'skins' ) ) {
132 $this->excludes[] = 'skins';
133 }
134 }
135
136 $this->doDot = (bool)shell_exec( 'which dot' );
137 }
138
139 public function execute() {
140 $this->init();
141
142 # Build out directories we want to exclude
143 $exclude = '';
144 foreach ( $this->excludes as $item ) {
145 $exclude .= " $item";
146 }
147
148 $conf = strtr( file_get_contents( $this->template ),
149 [
150 '{{OUTPUT_DIRECTORY}}' => $this->output,
151 '{{CURRENT_VERSION}}' => $this->mwVersion,
152 '{{INPUT}}' => $this->input,
153 '{{EXCLUDE}}' => $exclude,
154 '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
155 '{{INPUT_FILTER}}' => $this->inputFilter,
156 ]
157 );
158
159 $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
160 if ( file_put_contents( $tmpFile, $conf ) === false ) {
161 $this->fatalError( "Could not write doxygen configuration to file $tmpFile\n" );
162 }
163
164 $command = $this->doxygen . ' ' . $tmpFile;
165 $this->output( "Executing command:\n$command\n" );
166
167 $exitcode = 1;
168 system( $command, $exitcode );
169
170 $this->output( <<<TEXT
171---------------------------------------------------
172Doxygen execution finished.
173Check above for possible errors.
174
175You might want to delete the temporary file:
176 $tmpFile
177---------------------------------------------------
178
179TEXT
180 );
181
182 if ( $exitcode !== 0 ) {
183 $this->fatalError( "Something went wrong (exit: $exitcode)\n", $exitcode );
184 }
185 }
186}
187
188// @codeCoverageIgnoreStart
189$maintClass = MWDocGen::class;
190require_once RUN_MAINTENANCE_IF_MAIN;
191// @codeCoverageIgnoreEnd
wfTempDir()
Tries to get the system directory for temporary files.
Maintenance script that builds doxygen documentation.
Definition mwdocgen.php:47
__construct()
Prepare Maintenance class.
Definition mwdocgen.php:68
getDbType()
Does the script need different DB access? By default, we give Maintenance scripts normal rights to th...
Definition mwdocgen.php:92
execute()
Do the actual work.
Definition mwdocgen.php:139
Abstract maintenance class for quickly writing and churning out maintenance scripts with minimal effo...
output( $out, $channel=null)
Throw some output to the user.
fatalError( $msg, $exitCode=1)
Output a message and terminate the current script.
addOption( $name, $description, $required=false, $withArg=false, $shortName=false, $multiOccurrence=false)
Add a parameter to the script.
hasOption( $name)
Checks to see if a particular option was set.
getOption( $name, $default=null)
Get an option, or return the default.
addDescription( $text)
Set the description text.
Executes shell commands.
Definition Shell.php:46
$wgPhpCli
Config variable stub for the PhpCli setting, for use by phpdoc and IDEs.
$maintClass
Definition mwdocgen.php:189