Closed Bug 1556460 Opened 5 months ago Closed 8 days ago

|mach doc| broken with jsdoc >= 3.6: "No JSDoc documentation was found"

Categories

(Firefox Build System :: Generated Documentation, task, P3)

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: ahal, Assigned: erik)

References

(Blocks 1 open bug)

Details

User Story

Workaround:
Install JSDoc==3.5.5 from npm

Attachments

(2 files, 1 obsolete file)

We are currently pinned to sphinx-js==2.1 because the last time I tried to upgrade there were intermittents in the Doc task. I don't think I spent much time investigating as it was tangential to what I was working on at the time.

We should try to update it again, maybe the intermittents have solved themselves. If not, they are something we're going to need to fix sooner or later in order to pick up the (future) fix in https://github.com/mozilla/sphinx-js/issues/106 .

Type: defect → task
Priority: -- → P3

Depends on D33555

The above patches update |mach doc| to use sphinx-js==2.7.1. However I'm getting an error when running locally:

$ ./mach doc
...
WARNING: The config value `js_source_path' has type `list', defaults to `str'.
loading pickled environment... done
Cannot parse the config file tools/docs/jsdoc.json: Error: ENOENT: no such file or directory, open 'tools/docs/jsdoc.json'
Exiting JSDoc because an error occurred. See the previous log messages for details.

Sphinx error:
jsdoc found no JS files in the directories [u'/home/ahal/dev/mozilla-central/browser/components/extensions', u'/home/ahal/dev/mozilla-central/testing/marionette', u'/home/ahal/dev/mozilla-central/toolkit/components/extensions', u'/home/ahal/dev/mozilla-central/toolkit/components/extensions/parent', u'/home/ahal/dev/mozilla-central/toolkit/components/featuregates', u'/home/ahal/dev/mozilla-central/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/ahal/dev/mozilla-central/tools: sphinx return code 2

Erik, any idea what's happening here? Looks like trying to run jsdoc on a dir without JS files is now an error. If it helps I could figure out exactly which version of sphinx-js this starts happening with.

Flags: needinfo?(erik)

I think the first patch in that series is something we should do anyway and I see no reason not to land it.. so I'll get that pushed through here and leave-open to fix the sphinx-js update issues.

Attachment #9069483 - Attachment description: Bug 1556460 - [docs] Use compatible-release operator instead of * in tools/docs/Pipenv → Bug 1556460 - [docs] Use compatible-release operator instead of * in tools/docs/Pipenv, r?davehunt
Keywords: leave-open
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/f795f0184e3e
[docs] Use compatible-release operator instead of * in tools/docs/Pipenv, r=davehunt
User Story: (updated)
Keywords: leave-open
Summary: Upgrade sphinx-js → |mach doc| broken with jsdoc >= 3.6: "No JSDoc documentation was found"

Just putting a few things together here..

To solve this issue we need to:

  1. Fix the root problem in sphinx-js
  2. Upgrade to the new sphinx-js in ./mach doc (fixing any intermittents along the way)

In the meantime, we should:

  1. Print an error message if jsdoc>=3.6 is detected.
  2. Provide automatic bootstrapping of jsdoc (see also bug 1498604)

The workaround here is to downgrade jsdoc to version 3.5.x via npm.

See Also: → 1498604
Duplicate of this bug: 1579022

It's not true (at least for me) that jsdoc 3.6.3 is not working. After I got a similar error on bug 1579022 - which has a slightly different reason and I'm not sure if the dupe to this bug is actually correct - and I reinstalled jsdoc via npm, it's all working fine. So there must have been a broken dep or something else.

Interesting. Erik is also reporting that the issue seems to be magically resolved as well:
https://github.com/mozilla/sphinx-js/issues/106#issuecomment-531388659

So maybe there's nothing to do here? Maybe we should just use this bug to upgrade sphinx-js since we should do that anyway?

Flags: needinfo?(erik)

Sgtm. I'll cut a 2.8 release with some additional fixes and features (hopefully today) and then put up a patch.

Thanks! Just in case you missed it:

We are currently pinned to sphinx-js==2.1 because the last time I tried to upgrade there were intermittents in the Doc task.

Though who knows, maybe those issues are also magically solved :).

Spent the day getting CI passing with the latest jsdoc. So it's definitely working on 3.6.3 and will continue to. Did we ever finish switching moz-central over to Python 3? I'd like to make the release of sphinx-js after this one Python-3–only.

Btw, tests also pass fine with the latest Sphinx, but that version is Python-3–only, so I can't update CI to it just yet. That's my motivation.

2.8 release is cut.

Attachment #9069484 - Attachment is obsolete: true

The fix to bug 1232403 fixes this as well.

Status: NEW → RESOLVED
Closed: 8 days ago
Resolution: --- → FIXED

This is really my problem. :-) ahal was just reviewing for me.

Assignee: ahal → erik
Duplicate of this bug: 1587203
You need to log in before you can comment on or make changes to this bug.