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