Page MenuHomePhabricator

Make `npm run doc` work again for Page Previews
Closed, ResolvedPublic3 Story Points

Description

To help outsiders understand our code better AND to help us document the code we are writing better we should make it possible to generate our documentation again.

Currently, it floods the console with errors.

To fix:

  • Add mw global.
  • Allow global methods
  • Fix remaining documentation issues
  • Check generated docs and ensure they make sense
  • They're certainly beginning to!

Task should run on src/, and ignore resources/dist/.

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Restricted Application added a subscriber: TerraCodes. ยท View Herald TranscriptMar 6 2017, 9:26 PM
phuedx added a subscriber: phuedx.

Moving this to Triaged but Future as it's been in Sprint +1 for close to two months.

Jdlrobson renamed this task from Make `npm run doc` work again to Make `npm run doc` work again for Page Previews.Apr 24 2017, 7:44 PM
Jdlrobson lowered the priority of this task from High to Normal.
Jdlrobson updated the task description. (Show Details)
ovasileva raised the priority of this task from Normal to High.May 4 2017, 10:04 AM
Jdlrobson lowered the priority of this task from High to Normal.May 8 2017, 9:26 AM

Task should run on src/, and ignore resources/dist/.

I'll update description.

Jhernandez updated the task description. (Show Details)May 9 2017, 4:44 PM
Jhernandez updated the task description. (Show Details)May 9 2017, 4:47 PM
phuedx claimed this task.May 19 2017, 9:51 AM
phuedx moved this task from Needs Design Review to Doing on the Readers-Web-Kanbanana-Board-Old board.

Change 354455 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] WIP Make JSDuck Work Again

https://gerrit.wikimedia.org/r/354455

Change 355143 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document preview/model module

https://gerrit.wikimedia.org/r/355143

Change 355144 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document wait module

https://gerrit.wikimedia.org/r/355144

Change 355145 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] docs: Document schema module

https://gerrit.wikimedia.org/r/355145

^ Moving this to Needs Code Review so that the changes above'll be reviewed while I continue updating the documentation.

Change 355199 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document counts module

https://gerrit.wikimedia.org/r/355199

Change 355200 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document isEnabled module

https://gerrit.wikimedia.org/r/355200

All patches above have been merged

Change 354455 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Replace JSDuck v5.3.4 with JSDoc v3.4.3

https://gerrit.wikimedia.org/r/354455

Change 355143 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document preview/model module

https://gerrit.wikimedia.org/r/355143

Change 355144 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document wait module

https://gerrit.wikimedia.org/r/355144

Change 355145 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document schema module

https://gerrit.wikimedia.org/r/355145

Change 355199 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document counts module

https://gerrit.wikimedia.org/r/355199

Pew pew pew!!1

Change 355200 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document isEnabled module

https://gerrit.wikimedia.org/r/355200

phuedx updated the task description. (Show Details)May 24 2017, 8:50 AM

Change 355401 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document statsvInstrumentation module

https://gerrit.wikimedia.org/r/355401

Change 355474 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] WIP doc: Document gateway modules

https://gerrit.wikimedia.org/r/355474

Change 355401 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document statsvInstrumentation module

https://gerrit.wikimedia.org/r/355401

Change 355474 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document gateway modules

https://gerrit.wikimedia.org/r/355474

Change 355634 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document userSettings module

https://gerrit.wikimedia.org/r/355634

Change 355634 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document userSettings module

https://gerrit.wikimedia.org/r/355634

Change 355749 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/extensions/Popups@master] doc: Document reducers/eventLogging module

https://gerrit.wikimedia.org/r/355749

phuedx removed phuedx as the assignee of this task.May 26 2017, 9:12 AM
phuedx moved this task from Doing to Needs Code Review on the Readers-Web-Kanbanana-Board-Old board.

^ That's the last change that I have time to submit right now.

To reiterate, npm run doc runs just fine now and the documentation is taking shape. So, if you want, this task can be moved to Ready for Signoff.

IIRC @Jdlrobson said he might be interested in tidying up some other modules. Have at it!

Change 355749 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] doc: Document reducers/eventLogging module

https://gerrit.wikimedia.org/r/355749

Change 355807 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/extensions/Popups@master] Run doc generation on npm test

https://gerrit.wikimedia.org/r/355807

Change 355808 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/extensions/Popups@master] Docs: Don't register methods as globals in documentation

https://gerrit.wikimedia.org/r/355808

I've made a few minor changes to ensure our documentation doesn't break again and is a little cleaner. ^^

I think this is good enough for the time being. More patches are welcome but I think we've done enough here and we are certainly outside the original scope of this task

Change 355807 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] Run doc generation on npm test

https://gerrit.wikimedia.org/r/355807

Change 355808 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] Docs: Don't register methods as globals in documentation

https://gerrit.wikimedia.org/r/355808

Fix looks good, documentation is generated without errors, my only concern is that now we have two folders doc and docs, it's a bit confusing.
Doc folder contains only our documentation, docs autogenerated code documentation. I would look much cleaner with only one doc folder and a subfolder (for example, doc/code) which would contain generated documentation.

Change 356069 had a related patch set uploaded (by Pmiazga; owner: Pmiazga):
[mediawiki/extensions/Popups@master] Generate docs inside doc folder

https://gerrit.wikimedia.org/r/356069

Change 356069 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] Generate docs inside doc folder

https://gerrit.wikimedia.org/r/356069

pmiazga added a subscriber: bmansurov.

@bmansurov thanks for reviewing my small fix, code looks great, documentation generation works properly, no errors.

Jdlrobson closed this task as Resolved.May 30 2017, 11:27 PM
Jdforrester-WMF added a subscriber: Jdforrester-WMF.

Mass-moving all items tagged for MediaWiki 1.30.0-wmf.3, as that was never released; instead, we're using -wmf.4.