Last modified: 2014-11-15 21:17:42 UTC
On a patch set some discussion has arisen about PHPDoc[1]. This comes from using the latest specification of doxygen, that is apparently not used to generate the MediaWiki source documentation. [2] is using doxygen 1.7.6.1 instead of the more recent doxygen 1.8. [1] https://gerrit.wikimedia.org/r/#/c/56944/1/includes/specials/SpecialExport.php [2] https://doc.wikimedia.org/mediawiki-core/master/php/html/
Ubuntu 12.04 Precise ships doxygen 1.7.6.1-2ubuntu1. If you know a PPA it might speed up the process (e.g. Raring currently ships 1.8.3.1-1).
TLA PPA NU. ND. http://en.wikipedia.org/wiki/PPA Translated: three letter abbreviation PPA not understood. Needs disambiguation.
Search for "Ubuntu" on http://en.wikipedia.org/wiki/PPA , or the first "Ubuntu PPA" result on Google is https://launchpad.net/ubuntu/+ppas , but I agree that I should avoid such abbreviations or at least provide a link.
Homebrew repository has a doxygen package for 1.8.3.1: https://github.com/mxcl/homebrew/blob/f0986e690630edcb8d2716fedd7431dba79aa767/Library/Formula/doxygen.rb Seems a fairly straight forward installation process. Afaik nothing has changed since 1.7. Should't a re-build of the existing debian spec automatically package 1.8? Or is the one we inherited from ubuntu hardcoded for 1.7 somehow?
Ah, actually, debian.org already hosts a debian package for doxygen 1.8.x: http://packages.debian.org/search?keywords=doxygen It's in the wheezy channel though. Can we promote it to stable in our repo?
(In reply to comment #0) > On a patch set some discussion has arisen > https://gerrit.wikimedia.org/r/#/c/56944/1/includes/specials/SpecialExport. > php Actually the problem mentioned there wouldn't be solved by upgrading doxygen since that is the same in both 1.7.6 and 1.8.1 However there are lots of reasons to upgrade: - 1.7.6 is from 2011 - We use `backticks` for code samples and *emphasis* in our documentation, however that (Markdown formatting) was introduced in 1.8.0 and is currently breaking and causing weird stuff like: "This setting add supports for the `<img>` tag to result in output with literal * marks and the word <img> missing because it is interpreted as html. - 3 years of bug fixes and compatibility fixes for newer PHP versions (which we are using) http://www.stack.nl/~dimitri/doxygen/changelog.html (though potentially also regressions, but we have to try, right?) - ...
http://packages.ubuntu.com/precise/doxygen (doxygen 1.7.6) and http://packages.ubuntu.com/quantal/doxygen (doxygen 1.8.1) both have the exact same dependencies and versions thereof, so should be easy to import into our repo.
So this appears to be installing a new package for a single line of code, and I don't see a very compelling reason why this new package is better and that is possibly has regressions? If you would test this setup on labs with one new instance versus one old instance to make sure nothing breaks and show that there is a compelling reason to use the new package instead of the package maintained on stable, that would be compelling.
(In reply to comment #8) > So this appears to be installing a new package for a single line of code What code are you referring to? Assuming you mean the linked change by Siebranch in Gerrit in comment 0, you misunderstood. As I said in comment 6, that change is not relevant. That was a misinterpretation by Siebrand. The problem pointed out there wasn't a problem and even if it was, would NOT have been fixed by upgrading Doxygen. That change has been long merged, not blocked on this in any way. I've since repurposed this bug (as said in comment 6) because it was named exactly the same for what I needed. > I don't see a very compelling reason why this new package is better and that is > possibly has regressions? If you would test this setup on labs with one new > instance versus one old instance to make sure nothing breaks and show that > there is a compelling reason to use the new package instead of the package > maintained on stable, that would be compelling. The reason to upgrade is related to pending change https://gerrit.wikimedia.org/r/#/c/57905/. The problem is that Doxygen 1.7 has various bugs that are causing problems in our generated doxymentation. And there are various new features in 1.8 (such as the ability to escape characters). Right now it is not possible to mention something like "<img>" or "<script>" in PHP documentation, as Doxygen will render it on the doc pages as HTML, thus breaking the document flow. 1.8 introduces Markdown (instead of plain text with some annotations). This means we can use `backticks` (as I said before in comment 6) and inline annotations for emphasis.
(In reply to comment #8) I've already tested 1.8 locally and it is working fine with no regressions that I can see. I can set up 2 labs instances with Ubuntu and install 1.7 on one and 1.8 on another and both run it once on mediawiki/core to see the result. Let me know.
(In reply to comment #10) > (In reply to comment #8) > I've already tested 1.8 locally and it is working fine with no regressions > that > I can see. > > I can set up 2 labs instances with Ubuntu and install 1.7 on one and 1.8 on > another and both run it once on mediawiki/core to see the result. That would be great - Thanks
Moving this under 'Continuous integration' component so we can better keep track of it.
Timo, you can ask ops to backport Doxygen from a more recent version of Ubuntu. Usually a RT request and then hunting for someone from ops works :-]
Ubuntu Trusty ships Doxygen 1.8.6.
Over a year since Krinkle's last activity, removing as assignee. He knows how to re-add if he wants :)
Change 164354 had a related patch set uploaded by Hashar: (WIP) migrate mw doxygen to zuul-cloner and Trusty (WIP) https://gerrit.wikimedia.org/r/164354
This can be run on a Trusty labs instance which have doxygen 1.8.x. We also have the infrastructure to publish doc generated in labs to doc.wikimedia.org https://www.mediawiki.org/wiki/Continuous_integration/Documentation_generation Patch above is a work in progress.
WIP result: https://doc.wikimedia.org/hashar/mediawiki-core/master/php/html/ Compare with https://doc.wikimedia.org/mediawiki-core/master/php/html/
Change 166034 had a related patch set uploaded by Hashar: (WIP) migrate mw doxygen to zuul-cloner and Trusty (WIP) https://gerrit.wikimedia.org/r/166034
Change 164354 abandoned by Hashar: (WIP) migrate mw doxygen to zuul-cloner and Trusty (WIP) Reason: Migrated to integration/config as https://gerrit.wikimedia.org/r/#/c/166034/ https://gerrit.wikimedia.org/r/164354
Change 166034 merged by jenkins-bot: Migrate mw doxygen to zuul-cloner and Trusty https://gerrit.wikimedia.org/r/166034
Fixed by migrating the doxygen job from gallium to the Trusty labs instances.
