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