1151765 - use gulp to build jsdocs

Status: RESOLVED FIXED

(Firefox OS Graveyard :: Gaia::Build, defect)

Description

[[e-mail]]

We currently have grunt for jsdoc generation, to align with build script revice plan, it's better to do it with gulp

we can reuse existing jsdoc.json for gulp tasks

Comment 1

[GitHub Autolander Bot]

Attachment: [gaia] gasolin:issue-1151765 > mozilla-b2g:master

Comment 2

[[e-mail]]

The good news is its work, the bad news is the `gulp-jsdoc` plugin is not maintained.

Comment 3

[[e-mail]]

Comment on attachment 8589159 [details] [review]
[gaia] gasolin:issue-1151765 > mozilla-b2g:master

As comment above, the risk is we may need to fork our own version of gulp jsdoc plugin

Comment 4

[Ricky Chien [:rickychien] (inactive)]

Comment on attachment 8589159 [details] [review]
[gaia] gasolin:issue-1151765 > mozilla-b2g:master

Instead of maintaining a new jsdoc plugin, I'd like to babel transpiler to compile es6 to es5. We can fallback to fork our own version plugin if there are still problems.

Comment 5

[[e-mail]]

Comment on attachment 8589159 [details] [review]
[gaia] gasolin:issue-1151765 > mozilla-b2g:master

Good idea! after apply babel, the es6 functions can be transcompiled to general js and pass to jsdoc processor. Therefore the blacklist is minified now.

Comment 6

[Ricky Chien [:rickychien] (inactive)]

Comment on attachment 8589159 [details] [review]
[gaia] gasolin:issue-1151765 > mozilla-b2g:master

Nice job! r=me.

I leaved some comments on Github for build part review.

Comment 7

[GitHub Autolander Bot]

Attachment: [gaia-node-modules] gasolin:gulp-jsdoc > mozilla-b2g:master

Comment 8

[[e-mail]]

issue addressed,

merged https://github.com/mozilla-b2g/gaia/commit/9fc2df7b45974249064010bdaee4cdd1adb16ea3

thanks!

Comment 9

[Carsten Book [:Tomcat]]

this burned down b2g-inbound like https://treeherder.mozilla.org/logviewer.html#?job_id=1685967&repo=b2g-inbound and so i had to revert this

Comment 10

[Carsten Book [:Tomcat]]

and btw also caused https://treeherder.mozilla.org/logviewer.html#?job_id=809509&repo=gaia it seems

Comment 11

[Carsten Book [:Tomcat]]

seems the error was:

11:48:32 INFO - Unable to create a symbolic link from /home/worker/gaia/node_modules/gulp-jsdoc/node_modules/jsdoc/lib/jsdoc to /home/worker/gaia/node_modules/gulp-jsdoc/node_modules/jsdoc/node_modules/jsdoc. Error: EEXIST, symlink '/home/worker/gaia/node_modules/gulp-jsdoc/node_modules/jsdoc/lib/jsdoc'
11:48:32 INFO - npm ERR! jsdoc@3.3.0-alpha5 postinstall: `node ./node/postinstall.js`
11:48:32 INFO - npm ERR! Exit status 1
11:48:32 INFO - npm ERR!
11:48:32 INFO - npm ERR! Failed at the jsdoc@3.3.0-alpha5 postinstall script.
11:48:32 INFO - npm ERR! This is most likely a problem with the jsdoc package,
11:48:32 INFO - npm ERR! not with npm itself.
11:48:32 INFO - npm ERR! Tell the author that this fails on your system:
11:48:32 INFO - npm ERR! node ./node/postinstall.js
11:48:32 INFO - npm ERR! You can get their info via:
11:48:32 INFO - npm ERR! npm owner ls jsdoc
11:48:32 INFO - npm ERR! There is likely additional logging output above.
11:48:32 INFO - npm ERR! System Linux 3.13.0-27-generic
11:48:32 INFO - npm ERR! command "/usr/local/bin/node" "/usr/local/bin/npm" "rebuild"
11:48:32 INFO - npm ERR! cwd /home/worker/gaia
11:48:32 INFO - npm ERR! node -v v0.10.36
11:48:32 INFO - npm ERR! npm -v 1.4.28
11:48:32 INFO - npm ERR! code ELIFECYCLE
11:48:32 INFO - npm ERR!
11:48:32 INFO - npm ERR! Additional logging details can be found in:
11:48:32 INFO - npm ERR! /home/worker/gaia/npm-debug.log

Comment 12

[Kevin Grandon :kgrandon]

Also backed out from gaia-node-modules so we can keep things in sync: https://github.com/mozilla-b2g/gaia-node-modules/commit/8a8808a63f1989d95d1432b444a7ff2df07789e9

Comment 13

[[e-mail]]

would try to reland the patch once figure out why node_modules bark errors.

Comment 14

[GitHub Autolander Bot]

Attachment: [gaia] gasolin:issue-1151765-2 > mozilla-b2g:master

Comment 15

[GitHub Autolander Bot]

Attachment: [gaia-node-modules] gasolin:gulp-jsdoc-2 > mozilla-b2g:master

Comment 16

[[e-mail]]

soft link gaia-node-module to gaia folder to test it works, let's try land it again.

Comment 17

[[e-mail]]

gaia-node-modules 32431bccebaba44cfc557bf502b585ac57087c39

let's wait for treeherder result

Comment 18

[GitHub Autolander Bot]

Attachment: [gaia-node-modules] mozilla-b2g:revert-127-gulp-jsdoc-2 > mozilla-b2g:master

Comment 19

[[e-mail]]

failed, looks like soft link issue.

reverted https://github.com/mozilla-b2g/gaia-node-modules/pull/128

Comment 20

[GitHub Autolander Bot]

Attachment: [gaia] gasolin:issue-1151765-3 > mozilla-b2g:master

Comment 21

[[e-mail]]

Comment on attachment 8605715 [details] [review]
[gaia] gasolin:issue-1151765-3 > mozilla-b2g:master

previous implement depends on gulp-jsdoc, which is un-maintained and cause gaia_node_module error when landing.

The new approach modify the gulpfile.js and use gulp-shell to run jsdoc, and the jsdoc.json format is updated to real jsdoc config format 
http://usejsdoc.org/about-configuring-jsdoc.html

It means each app could manage their preferred jsdoc output as well.

Comment 22

[Ricky Chien [:rickychien] (inactive)]

Comment on attachment 8605715 [details] [review]
[gaia] gasolin:issue-1151765-3 > mozilla-b2g:master

Thanks fred! it looks good to me.

Remember to update README.md at https://github.com/mozilla-b2g/gaia#generate-jsdoc for document new gulp command. thanks!

Comment 23

[GitHub Autolander Bot]

Attachment: [gaia-node-modules] gasolin:gulp-jsdoc-3 > mozilla-b2g:master

Comment 24

[GitHub Autolander Bot]

Attachment: [gaia-node-modules] mozilla-b2g:revert-138-gulp-jsdoc-3 > mozilla-b2g:master

Comment 25

[[e-mail]]

merged to https://github.com/mozilla-b2g/gaia/commit/9ba8cb4ef2e0344b70f189e5b587d5d703f22d93

thanks!