3 * Generate class and file reference documentation for MediaWiki using doxygen.
5 * If the dot DOT language processor is available, attempt call graph
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.
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.
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
28 * @ingroup Maintenance
30 * @author Antoine Musso <hashar at free dot fr>
31 * @author Brion Vibber
32 * @author Alexandre Emsenhuber
33 * @version first release
36 use MediaWiki\Shell\Shell
;
38 require_once __DIR__
. '/Maintenance.php';
41 * Maintenance script that builds doxygen documentation.
42 * @ingroup Maintenance
44 class MWDocGen
extends Maintenance
{
60 private $excludePatterns;
67 * Prepare Maintenance class
69 public function __construct() {
70 parent
::__construct();
71 $this->addDescription( 'Build doxygen documentation' );
73 $this->addOption( 'doxygen',
76 $this->addOption( 'version',
77 'Pass a MediaWiki version',
79 $this->addOption( 'file',
80 "Only process given file or directory. Multiple values " .
81 "accepted with comma separation. Path relative to \$IP.",
83 $this->addOption( 'output',
84 'Path to write doc to',
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)' );
92 public function getDbType() {
93 return Maintenance
::DB_NONE
;
96 protected function init() {
97 global $wgPhpCli, $IP;
99 $this->doxygen
= $this->getOption( 'doxygen', 'doxygen' );
100 $this->mwVersion
= $this->getOption( 'version', 'master' );
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\"";
109 $this->output
= $this->getOption( 'output', "$IP/docs" );
111 // Do not use wfShellWikiCmd, because mwdoc-filter.php is not
112 // a Maintenance script.
113 $this->inputFilter
= Shell
::escape( [
115 $IP . '/maintenance/mwdoc-filter.php'
118 $this->template
= $IP . '/maintenance/Doxyfile';
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';
134 if ( !$this->hasOption( 'skins' ) ) {
135 $this->excludePatterns
[] = 'skins';
139 $this->doDot
= shell_exec( 'which dot' );
142 public function execute() {
147 # Build out directories we want to exclude
149 foreach ( $this->excludes
as $item ) {
150 $exclude .= " $IP/$item";
153 $excludePatterns = implode( ' ', $this->excludePatterns
);
155 $conf = strtr( file_get_contents( $this->template
),
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
,
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" );
173 $command = $this->doxygen
. ' ' . $tmpFile;
174 $this->output( "Executing command:\n$command\n" );
177 system( $command, $exitcode );
179 $this->output( <<<TEXT
180 ---------------------------------------------------
181 Doxygen execution finished.
182 Check above for possible errors.
184 You might want to delete the temporary file:
186 ---------------------------------------------------
191 if ( $exitcode !== 0 ) {
192 $this->fatalError( "Something went wrong (exit: $exitcode)\n", $exitcode );
197 $maintClass = MWDocGen
::class;
198 require_once RUN_MAINTENANCE_IF_MAIN
;