1592964 - jsdoc: add minimal version

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, task)

Description

[Sylvestre Ledru [:Sylvestre]]

In Debian and Ubuntu, jsdoc is version 2.4 (pretty old).
See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=739506 for more information about that.

However, as the error message is cryptic:

Creating file /home/sylvestre/dev/mozilla/mozilla-inbound.hg/obj-x86_64-pc-linux-gnu/docs/html/_staging/python/marionette_driver.rst.
WARNING: The config value `js_source_path' has type `list', defaults to `str'.

Sphinx error:
jsdoc found no JS files in the directories [u'/home/sylvestre/dev/mozilla/mozilla-inbound.hg/browser/components/extensions', u'/home/sylvestre/dev/mozilla/mozilla-inbound.hg/testing/marionette', u'/home/sylvestre/dev/mozilla/mozilla-inbound.hg/toolkit/components/extensions', u'/home/sylvestre/dev/mozilla/mozilla-inbound.hg/toolkit/components/extensions/parent', u'/home/sylvestre/dev/mozilla/mozilla-inbound.hg/toolkit/components/featuregates', u'/home/sylvestre/dev/mozilla/mozilla-inbound.hg/toolkit/mozapps/extensions']. Make sure js_source_path is set correctly in conf.py. It is also possible (though unlikely) that jsdoc emitted invalid JSON.
./mach: failed to generate documentation:
/home/sylvestre/dev/mozilla/mozilla-inbound.hg/tools: sphinx return code 2

We should give more information in case of error (at least the version)

Comment 1

[Sylvestre Ledru [:Sylvestre]]

Attachment: Bug 1592964 - Detail the minimal version of jsdoc expected r?ahal

Comment 2

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/d60821c527f2
Detail the minimal version of jsdoc expected r=ahal

Comment 3

[Arthur Iakab [arthur_iakab]]

https://hg.mozilla.org/mozilla-central/rev/d60821c527f2

Comment 4

[Andrew Halberstadt [:ahal]]

Due to bug 1556460 we actually fail with jsdoc>=3.6.0. Until we figure out why, let's do a version check and update our message.

Comment 5

[Andrew Halberstadt [:ahal]]

Attachment: Bug 1592964 = [docs] Error out if we detect anything but jsdoc==3.5, r?Sylvestre

More modern versions of jsdoc fail due to bug 1556460.

Comment 6

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/7dbfb4cac809
= [docs] Error out if we detect anything but jsdoc==3.5, r=sylvestre

Comment 7

[Andreea Pavel [:apavel]]

https://hg.mozilla.org/mozilla-central/rev/7dbfb4cac809