Add JSDoc to docs build environment

[raucao]

Details

• Project URL: https://readthedocs.org/projects/remotestoragejs
• Build URL (if applicable): https://readthedocs.org/projects/remotestoragejs/builds/5893794/
• Read the Docs username (if applicable): raucao

Expected Result

Use sphinx-js extension to pull in JavaScript function references and documentation (not entirely expected, but it would be fantastic)

Actual Result

No jsdoc executable available, nor possible to install via PIP dependencies.

Explanation / Feature request

The recently launched sphinx-js extension is a great way to mix JSDoc source code docs with ReST documentation. It adds directives which are similar to the Python-specific autodoc ones. Here's a good introductory blog post by the Mozillian who created it:

https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/

Afaics, the "only" thing missing to get this working on Read the Docs would be to add the jsdoc program to the environment that is used to build docs on RtD. I believe this would be a great addition, which would enable all JavaScript developers to better document their code.

---

Disclaimer: the docs linked above are mostly stubs. We're in the process of releasing a new major version of our JS library, and only just started writing proper documentation for it.

[wmnnd]

This is odd since jsdoc was previously available on RTD. A project using sphinx-js that was previously build fine has now stopped working on RTD without any changes to the project configuration:
https://readthedocs.org/projects/dblsqd-node-sdk/builds/

It doesn't look like jsdoc was removed from the Docker image, it is still being installed as per the commit by @adambrenecki:
https://github.com/rtfd/readthedocs-docker-images/blob/master/Dockerfile#L48

[agjohnson]

jsdoc was added, but the images haven't been released to the build servers in some time. I'll add this to my list this week.

[raucao]

Any chance of getting the images out soon-ish? Can I help somehow?

[daisylb]

On Lorikeet, which uses JSDoc, I had a build that completed on Sept. 16, 2017. 9:18 p.m. (not sure which timezone, but it's not my local one); more recent builds have started failing again. So I guess the new image is being used for some builds but not all?

[raucao]

Weird, another build passed, but then failed again: https://readthedocs.org/projects/remotestoragejs/builds/

[raucao]

@agjohnson Any chance you could update the images this week maybe? We're planning to publish a big new version of our library end of this or beginning of next week, which includes the switch to RST, JSDoc and Read the Docs...

[raucao]

So, until today we had a ~50% chance of the builds passing, but now all of them are failing. It seems like the worker(s) that already used the new image are not in use anymore, or at least not used for our docs (I have no idea how that stuff is set up, so just my hunch from the outside). Here's what the history of https://readthedocs.org/projects/remotestoragejs/builds/ looks like:

It'd be fantastic, if someone could finally update the images in production, so that we and other projects are able to build JavaScript API docs using sphinx-js (or JSDoc in some other way)!

[agjohnson]

The images were updated this week. If you're projects aren't using the latest build image, that is the cause. I'm really not sure how jsdoc made it into our 2.x series of images frankly, it wasn't backported.

@skddc i've set the container image to the latest version for your project, see if that helps.

[raucao]

Thanks! Unfortunately, that change seems to have broken the builds a bit more: https://readthedocs.org/projects/remotestoragejs/builds/6176840/

There's a "permission denied" for the first command already.

[agjohnson]

Can you try wiping your build? I think this is a matter of the old environment persisting

[raucao]

Yay, that worked! Thanks a lot!

[crccheck]

Hi. jsdoc still seems to be unavailable. I just started a new project and I keep getting FileNotFoundError: [Errno 2] No such file or directory: 'jsdoc'. I've tried wiping, Python 3.5 and Python 2.7

https://readthedocs.org/projects/launch-vehicle-fbm/builds/

[agjohnson]

@crccheck noted above, you need access to our latest build image, the default image is not our latest image but the 2.0 series image. I'll change your project to use the new build image.

Note, as per the issue above as well, you'll need to wipe your build env first.

[crccheck]

Sorry, I got some followup questions:

you need access to our latest build image

Is that a project setting I have access to? I can't find anything that could do that besides changing Python versions. Is everyone that wants to use sphinx-js going to need to ask an admin to enable it?

the default image is not our latest image but the 2.0 series image

Is "latest" newer or older than the 2.0 series? For example, a lot of Docker builds have their latest on 1.x while publishing 2.x builds.

[agjohnson]

Is that a project setting I have access to? I can't find anything that could do that besides changing Python versions.

Nope, not yet. This will be user configurable at some point in the future.

Is "latest" newer or older than the 2.0 series?

We follow semantic versioning, our latest docker image is probably most technically 3.0bNUMBERS, but we aren't explicit about pre releases.

[dselman]

Using sphinx_js doesn't seem to work for a project I created this week. See:
https://github.com/erikrose/sphinx-js/issues/35

@agjohnson is there something you can do on your end? My project is:
https://readthedocs.org/projects/accordcicero/builds/

[dselman]

I confirmed that the 2.0 version of the Dockerfile does not contain the npm jsdoc module:
https://raw.githubusercontent.com/rtfd/readthedocs-docker-images/releases/2.x/Dockerfile

This is included in the latest Dockerfile however. Is there any way to specify which version of the Docker image to use?

[agjohnson]

We're working on a method now! Having this user configurable probably makes a lot of sense for us.

[jwflory]

Hi! I tried setting this up for a project and hit the same issue as others above. Could we have our image updated for this project?

Never mind. I read the docs and found the bit about using a .readthedocs.yml config file to build the latest version. Seems like everything is building okay now. A UI option would definitely be awesome. 🙂

[jpic]

Hi all !

I have tried the solution by @jflory7 but it still fails when trying to execute jsdoc:

FileNotFoundError: [Errno 2] No such file or directory: 'jsdoc'

UPDATE, i had a typo in my YAML, silly me :D

Awesome: http://facond.readthedocs.io/en/latest/forms.html

[dhdaines]

Hi, how does one do this with a v2 configuration file? Is jsdoc included with the nodejs plugin? Can the documentation be updated?

EDIT: I can install jsdoc-toolkit using the apt_packages configuration parameter ... but it still doesn't actually work, either it can't find my JS files or there is a JSON parsing error, unsure how to tell which is which from the exception message.

EDIT: It still works, you just need to use the "legacy build specification": https://docs.readthedocs.io/en/latest/config-file/v2.html#legacy-build-specification - see my .readthedocs.yml here: https://github.com/ReadAlongs/SoundSwallower/blob/master/.readthedocs.yml

[humitos]

Hi @dhdaines. You should not use build.image on new configs since it's deprecated and will be removed eventually. I recommend you to use something like:

build:
  os: ubuntu-22.04
  tools:
    python: "3.9"
    nodejs: "16"
  jobs:
    post_install:
      - npm install -g jsdoc

You can see a full working example at https://test-builds.readthedocs.io/en/jsdoc/

Let me know if that works for you.

[dhdaines]

Thank you @humitos ! Yes, it works great now. I did not know that I was able to install npm packages from the v2 config file...

[dhdaines]

Also, I did not know that test-builds.readthedocs.io existed! Is it something that everyone can use to test their RTD configs? Is it documented somewhere?

[humitos]

Also, I did not know that test-builds.readthedocs.io existed! Is it something that everyone can use to test their RTD configs? Is it documented somewhere?

test-builds it's a repository that we use internally at Read the Docs to create different use cases and make sure we (don't) support them over time, testing different combinations of the config file and others. It's not intended for users to use, but I thought that branch would be a good example of all the pieces working together.