- make sure CI isn't broken (sign of an abandoned extension)
- get JSDoc + jsdoc-wmf-theme installed, with npm run jsdoc working and /docs/js viewable
- compare it to JSDuck site, make sure it's identical, fix anything as needed. check both left menu and homepage. homepage has some extra stuff on it that isn't in the left menu
- create / make sure it has a readme, in markdown. make sure the readme links to the extension on mediawiki.org
- switch JSDuck for JSDoc on doc.wikimedia.org (by switching npm run doc to jsdoc. after that it will deploy instantly and the cache will clear in an hour)
- delete any remaining JSDuck code
- add && npm run doc to the npm test script
Description
Description
Details
Details
Related Changes in Gerrit:
| Subject | Repo | Branch | Lines +/- | |
|---|---|---|---|---|
| convert from JSDuck to JSDoc | mediawiki/extensions/GuidedTour | master | +681 -282 |
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Open | Feature | None | T263914 Offer TypeScript declaration files for the MediaWiki Javascript API (MediaWiki API typings) | ||
| Resolved | hashar | T213282 JSDuck at doc.wikimedia.org loads fonts from google | |||
| Open | None | T334853 Clean up JS code now that we can use ES6 rather than ES5 across all Wikimedia deployed codebases | |||
| Stalled | None | T363905 Uninstall jsduck and related material from CI images etc., once it's no longer needed | |||
| Resolved | apaskulin | T138401 Replace jsduck with JSDoc3 across all Wikimedia code bases | |||
| Resolved | Novem_Linguae | T367507 Replace jsduck with JSDoc3 in GuidedTour |
Event Timeline
Comment Actions
Change #1043786 had a related patch set uploaded (by Novem Linguae; author: Novem Linguae):
[mediawiki/extensions/GuidedTour@master] JSDoc: initial setup
Comment Actions
Hmm, that's interesting. In this patch, I got the /docs/js/ site to build, and most of it works, but when I click on mw.guidedTour, I get a 404 error.
An examination of the directory structure shows the weird file mw.html#.guidedTour instead of the expected mw.guidedTour.html. Ever seen this before @apaskulin? Note that it still does this when I turn off jsdoc-wmf-theme.
Comment Actions
Looks like this is caused by https://gerrit.wikimedia.org/g/mediawiki/extensions/GuidedTour/+/master/modules/ext.guidedTour.lib/ext.guidedTour.lib.TransitionEvent.js#79 which JSDoc is interpreting as a property named guidedTour belonging to the class mw, which then conflicts with the class named mw.guidedTour. Adding @ignore to that docblock fixes the issues and causes mw.guidedTour.html to generate correctly.
I'm not totally sure what the best way is to fix this. Looking at these properties in JSDuck, they seem to be properties for a private method, so maybe adding @ignore to the docblock causing the issue would be fine.
Comment Actions
Change #1043786 merged by jenkins-bot:
[mediawiki/extensions/GuidedTour@master] convert from JSDuck to JSDoc
Comment Actions
This is now done! See https://doc.wikimedia.org/GuidedTour/master/js/js/index.html. Thanks, @Novem_Linguae!