MediaWiki REL1_34
mwdocgen.php
Go to the documentation of this file.
1<?php
37
38require_once __DIR__ . '/Maintenance.php';
39
44class 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;
64 private $doMan;
65
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() {
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---------------------------------------------------
181Doxygen execution finished.
182Check above for possible errors.
183
184You might want to delete the temporary file:
185 $tmpFile
186---------------------------------------------------
187
188TEXT
189 );
190
191 if ( $exitcode !== 0 ) {
192 $this->fatalError( "Something went wrong (exit: $exitcode)\n", $exitcode );
193 }
194 }
195}
196
197$maintClass = MWDocGen::class;
198require_once RUN_MAINTENANCE_IF_MAIN;
$wgPhpCli
Executable path of the PHP cli binary.
wfTempDir()
Tries to get the system directory for temporary files.
const RUN_MAINTENANCE_IF_MAIN
$IP
Definition WebStart.php:41
$command
Definition cdb.php:65
Maintenance script that builds doxygen documentation.
Definition mwdocgen.php:44
string[] $excludePatterns
Definition mwdocgen.php:60
string $output
Definition mwdocgen.php:50
string[] $excludes
Definition mwdocgen.php:58
bool $doDot
Definition mwdocgen.php:62
string $inputFilter
Definition mwdocgen.php:54
bool $doMan
Definition mwdocgen.php:64
string $doxygen
Definition mwdocgen.php:46
string $template
Definition mwdocgen.php:56
string $input
Definition mwdocgen.php:52
__construct()
Prepare Maintenance class.
Definition mwdocgen.php:69
string $mwVersion
Definition mwdocgen.php:48
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:142
Abstract maintenance class for quickly writing and churning out maintenance scripts with minimal effo...
const DB_NONE
Constants for DB access type.
output( $out, $channel=null)
Throw some output to the user.
hasOption( $name)
Checks to see if a particular option exists.
addDescription( $text)
Set the description text.
addOption( $name, $description, $required=false, $withArg=false, $shortName=false, $multiOccurrence=false)
Add a parameter to the script.
getOption( $name, $default=null)
Get an option, or return the default.
fatalError( $msg, $exitCode=1)
Output a message and terminate the current script.
Executes shell commands.
Definition Shell.php:44
$maintClass
Definition mwdocgen.php:197