Why:
* Maintenance scripts in core have bolierplate code that is
added before and after the class to allow directly running
the maintenance script.
* Running the maintenance script directly has been deprecated
since 1.40, so this boilerplate code is only to support a now
deprecated method of running maintenance scripts.
* This code cannot also be marked as covered, due to PHPUnit
not recognising code coverage for files.
* Therefore, it is best to ignore this boilerplate code in code
coverage reports as it cannot be marked as covered and also
is for deprecated code.
What:
* Wrap the boilerplate code (requiring Maintenance.php and then
later defining the maintenance script class and running if the
maintenance script was called directly) with @codeCoverageIgnore
comments.
* Some files use a different boilerplate code, however, these
should also be marked as ignored for coverage for the same
reason that coverage is not properly reported for files.
Bug: T371167
Change-Id: I32f5c6362dfb354149a48ce9c28da9a7fc494f7c
Follows-up:
* I696f1e7ede (60f106e112): Apply `vendor` and `node_modules` exclude
patterns even when `--file` is used to generate docs for an extension
or a subset of core.
* I9313457796 (eaf491b4f4): Use faster and upstream supported EXCLUDE
instead of EXCLUDE_PATTERNS for skipping whole top-level dirs.
Neither of these addressed the fact that this `if` condition is not
actually possible to reach because `explode()` always returns an
array with at least one item. e.g. `exclude(',', '') == [ '' ]`.
Test plan:
* `php maintenance/mwdocgen.php --output ./docs/ --version whatever`
* Review the contents the mentioned `/tmp/MWDocGen-*` file that is
auto-generated.
Before:
```
INPUT = ""
…
EXCLUDE = cache images
```
After:
```
INPUT =
…
EXCLUDE = cache images extensions skins
```
Bug: T317451
Change-Id: I871b321fa9fdb2d763fba532ab6248b0fc4b1701
* Prefer the MW_INSTALL_PATH constant where possible.
* For input and output, there is no need to specify full paths,
only to strip the prefix again afterwards.
See also Doxyfile in any repo that is not mediawiki/core where we
already set the path relative to the project directory, e.g.
"src/" as input and "docs" as output.
<https://codesearch.wmcloud.org/search/?q=INPUT%7COUTPUT&files=Doxyfile>
Test Plan:
* `php maintenance/mwdocgen.php --file docs,includes/libs/objectcache/`
Change-Id: I4119161accdc665d0e4d0d4e49d0c42c68f8e2a2
Updating name & email addresses for Brooke Vibber.
Re-ran updateCredits.php as well so there are some new entries in
there as well.
There are a couple of files in resources/libs that will have to
be changed upstream to keep tests happy, I will do patches
later. :D
Change-Id: I2f2e75d3fa42e8cf6de19a8fbb615bac28efcd54
For reasons not yet understood, during CI jobs for Git release tags,
the doc publishing pipeline is scanning extensions directories even
on core-only builds.
This was realized when investigating an issue with a large fixture
file in extensions/CirrusSearch/tests/ ("interwiki.php") causing
Doxygen to crash.
When reproducing the issue locally, I found that numerous node_modules,
vendor were also being scanned that didn't need to be.
Also exclude the 'cache' dir from core $IP while at it.
Bug: T317451
Change-Id: I696f1e7edeaf7bf12fbf17613cc9ee5c8dd846b0
php internal functions like floor/round/ceil documented to return
float, most cases the result is used as int, added casts
Found by phan strict checks
Change-Id: I92daeb0f7be8a0566fd9258f66ed3aced9a7b792
The default was previously to index all of core and extensions,
which is likely not the intent of someone running this for the
first time (which can then easily take over half an hour).
Even in CI, we never do this, and we never have afaik.
Generally, local use is to replicate CI (all of core), or a subset
of core by passing e.g. '--file includes/libs' or some such.
Indexing an extension is still possible, same way as before,
by passing '--file extensions/FooBar'. And, if one really wants
to index all of core and all extensions, the new '--extensions'
option allows one to opt back in to the old behaviour.
Also:
* Exclude all of 'resources/'. There are no PHP or Markdown files
here that need to be indexed.
Bug: T232104
Change-Id: I55617776ac86f3fdcb6c1ba1eebe892edcb5fafb
This makes it more future-proof so that when more files are
added, they are excluded by default. If and when we do get a file
that is intended for this, it's likely such commit will test it
and find it doesn't work and then whitelist accordingly.
Change-Id: I3b8e421724d45e6aaecea58238f430a87cbbe977
Cleans up the Doxygen file list by excluding markdown
files other than the intro, main code of conduct, and
/docs directory.
docs: Add heading to code of conduct
Adds an h1 heading to use as the file listing
in Doxygen instead of the file name.
Change-Id: Id13eec2670aa4b96275f1e688a29c22c3f38a859
Also remove redundant sections from the config file that all
relate to features that are unconditionally disabled for us
and by default. They were all no-ops because the corresponding
"GENERATE_"- config is NO by default as well.
Per <http://www.doxygen.nl/manual/config.html>.
Bug: T232104
Change-Id: Ibd81f23922f1994be6579fcd8e1ece5e9f995905
Follows-up b7c5acd419, which started indexing .md files
anywhere in core. While these are harmless to analyse (they're
not going to find any meaningful doc blocks), it just adds
more noise to the file listing.
Bug: T232104
Change-Id: Ibd2010010872d42dc3d52139305c87fcfc547477
Deprecate the second argument to Maintenance::error() in favor of a new
Maintenance::fatalError() method. This is intended to make it easier to
review flow control in maintenance scripts.
Change-Id: I75699008638f7e99b11210c7bb9e2e131fca7c9e
They are exactly equivalent, but shell_exec is more readable.
We just imported a sniff to forbid backtick into mediawiki-codesniffer.
It's not deployed here yet, but this will facilitate it.
Change-Id: I4b58ed78e1792ff83e1bf99425f8f19123cfe911
Revert a58948d64 and instead remove wfShellWikiCmd and escape
shell arguments directly.
This should be fine since mwdoc-filter.php does not depend on per-wiki
state.
Change-Id: Id9c6ca84bab827675b71ca16bf688fd3f5c993a1
https://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_quiet
* To make the standard output in Jenkins more useful,
disable the verbose messages about "Loading file .." in between
all the errors.
* Remove obsolete config options XML_SCHEMA and XML_DTD that were
producing warnings. We weren't using these anyway (set to their default
blank value).
Change-Id: I6876cf4d783f7795a12d99623c8ce3717e9a51f5
So that local runs don't take forever and won't recurse into unrelated
php files in some npm package.
Change-Id: Ic8068fa048075584c9334d0c21fb4efd87eade02
It is sometimes useful to generate documentation for multiple files or
directories. Doxygen INPUT statement supports multiple space separated
paths. Example usage:
php maintenance/mwdocgen.php --file docs,input
Change-Id: I66a805d80307c6502e9b440df63a37bb13093d84
Now that we support composer libraries we should exclude vendor/
so that our Doxygen script doesn't go generating documentation
for 3rd party libraries we use.
Change-Id: I40502015820f0b9b4b1ef5810bcddcc5970134c5
Now based on Maintenance class.
Reinstate {{EXCLUDE}} which got removed by 8199984
This is roughly back compatible.
bug: 34436
Change-Id: Ic1a2b2c29718054ec740b2ffb90350af700a6a58
Follows-up I1343872de7, Ia533aedf63 and I2df2f80b81.
Also updated usage in text in documentation and the
installer LocalSettingsGenerator.
Most of them were handled by this regex:
- find: (require|include|require_once|include_once)\s*\(\s*(.+?)\s*\)\s*;$
- replace: $1 $2;
Change-Id: I6b38aad9a5149c9c43ce18bd8edbab14b8ce43fa
So that the job that runs it can pass along what it should
display (e.g. branch, tag, hash etc. whatever is appropiate
for the context of that run).
Change-Id: I1d5b6266e49a71672b0a53069e6ea6bb4658c3d2
Previously it just naturally exited which means even if the
doxygen bin doesn't exist, it'll return "success".
Bug: 46151
Change-Id: Ie1e3d956ce5d3e1f28c7c829bb57596113f07c4a
Fix up spaces in our function calls, we do not want spaces before a
comma and try to avoid multiple commas whenever possible.
Errors:
* No space found after comma in function call
* Space found before comma in function call
Change-Id: I51aec02016f742422fa60b92ad35ba3f0ef59ba3
The PHP_SAPI constant has been available since PHP 4.2.0. It's more
concise to use the constant and has less overhead than a function call.
Furthermore, PHP_SAPI rhymes with "happy", whereas "php_sapi_name"
rhymes with "lame". QED, etc.
Change-Id: Ie8c121cb8fcef50536af8d3f66723b458f0bf9af
We can now do this since we finally switched to PHP 5.3 for MW 1.20 and get rid of the silly dirname(__FILE__) stuff :)
Change-Id: Id9b2c9cd2e678197aa81c78adced5d1d31ff57b1
When running mwdocgen.php outside of maintenance, the input filter was
not found. Giving the full path fix the issue.
Issue introduced by I4ead1bd1 / ab59fad.
Change-Id: I5e28209eba1afd24d60b2dc940b9f5dfb1b4f34c
Tweaked mwdocgen.php to let us generates man pages. They will be saved to
./docs/man so make sure to update your MANPATH if you use this feature.
Usage:
php mwdocgen.php --all --generate-man
or
make man
