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;
60  private $excludePatterns;
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 \$IP.",
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() {
91  return Maintenance::DB_NONE;
92  }
93 
94  protected function init() {
95  global $wgPhpCli, $IP;
96 
97  $this->doxygen = $this->getOption( 'doxygen', 'doxygen' );
98  $this->mwVersion = $this->getOption( 'version', 'master' );
99 
100  $this->input = '';
101  $inputs = explode( ',', $this->getOption( 'file', '' ) );
102  foreach ( $inputs as $input ) {
103  # Doxygen inputs are space separated and double quoted
104  $this->input .= " \"$IP/$input\"";
105  }
106 
107  $this->output = $this->getOption( 'output', "$IP/docs" );
108 
109  // Do not use wfShellWikiCmd, because mwdoc-filter.php is not
110  // a Maintenance script.
111  $this->inputFilter = Shell::escape( [
112  $wgPhpCli,
113  $IP . '/maintenance/mwdoc-filter.php'
114  ] );
115 
116  $this->template = $IP . '/maintenance/Doxyfile';
117  $this->excludes = [
118  'cache',
119  'images',
120  ];
121  $this->excludePatterns = [];
122  if ( $this->input === '' ) {
123  // If no explicit --file filter is set, we're indexing all of $IP,
124  // but any extension or skin submodules should be excluded by default.
125  if ( !$this->hasOption( 'extensions' ) ) {
126  $this->excludePatterns[] = 'extensions';
127  }
128  if ( !$this->hasOption( 'skins' ) ) {
129  $this->excludePatterns[] = 'skins';
130  }
131  }
132 
133  $this->doDot = (bool)shell_exec( 'which dot' );
134  }
135 
136  public function execute() {
137  global $IP;
138 
139  $this->init();
140 
141  # Build out directories we want to exclude
142  $exclude = '';
143  foreach ( $this->excludes as $item ) {
144  $exclude .= " $IP/$item";
145  }
146 
147  $excludePatterns = implode( ' ', $this->excludePatterns );
148 
149  $conf = strtr( file_get_contents( $this->template ),
150  [
151  '{{OUTPUT_DIRECTORY}}' => $this->output,
152  '{{STRIP_FROM_PATH}}' => $IP,
153  '{{CURRENT_VERSION}}' => $this->mwVersion,
154  '{{INPUT}}' => $this->input,
155  '{{EXCLUDE}}' => $exclude,
156  '{{EXCLUDE_PATTERNS}}' => $excludePatterns,
157  '{{HAVE_DOT}}' => $this->doDot ? 'YES' : 'NO',
158  '{{INPUT_FILTER}}' => $this->inputFilter,
159  ]
160  );
161 
162  $tmpFile = tempnam( wfTempDir(), 'MWDocGen-' );
163  if ( file_put_contents( $tmpFile, $conf ) === false ) {
164  $this->fatalError( "Could not write doxygen configuration to file $tmpFile\n" );
165  }
166 
167  $command = $this->doxygen . ' ' . $tmpFile;
168  $this->output( "Executing command:\n$command\n" );
169 
170  $exitcode = 1;
171  system( $command, $exitcode );
172 
173  $this->output( <<<TEXT
174 ---------------------------------------------------
175 Doxygen execution finished.
176 Check above for possible errors.
177 
178 You might want to delete the temporary file:
179  $tmpFile
180 ---------------------------------------------------
181 
182 TEXT
183  );
184 
185  if ( $exitcode !== 0 ) {
186  $this->fatalError( "Something went wrong (exit: $exitcode)\n", $exitcode );
187  }
188  }
189 }
190 
191 $maintClass = MWDocGen::class;
192 require_once RUN_MAINTENANCE_IF_MAIN;
wfTempDir()
Tries to get the system directory for temporary files.
if(!defined( 'MEDIAWIKI')) if(ini_get( 'mbstring.func_overload')) if(!defined( 'MW_ENTRY_POINT')) global $IP
Environment checks.
Definition: Setup.php:91
Maintenance script that builds doxygen documentation.
Definition: mwdocgen.php:44
__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:136
Abstract maintenance class for quickly writing and churning out maintenance scripts with minimal effo...
Definition: Maintenance.php:66
const DB_NONE
Constants for DB access type.
Definition: Maintenance.php:71
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:191