New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add JSDoc to docs build environment #3069

Closed
skddc opened this Issue Aug 28, 2017 · 20 comments

Comments

Projects
None yet
9 participants
@skddc

skddc commented Aug 28, 2017

Details

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 comment has been minimized.

wmnnd commented Aug 30, 2017

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

This comment has been minimized.

Contributor

agjohnson commented Sep 11, 2017

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.

@skddc

This comment has been minimized.

skddc commented Sep 22, 2017

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

@adambrenecki

This comment has been minimized.

adambrenecki commented Sep 24, 2017

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?

@skddc

This comment has been minimized.

skddc commented Oct 2, 2017

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

@skddc

This comment has been minimized.

skddc commented Oct 2, 2017

@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...

@skddc

This comment has been minimized.

skddc commented Oct 24, 2017

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:

screenshot from 2017-10-24 18-52-25

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

This comment has been minimized.

Contributor

agjohnson commented Oct 25, 2017

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.

@skddc

This comment has been minimized.

skddc commented Oct 25, 2017

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

This comment has been minimized.

Contributor

agjohnson commented Oct 25, 2017

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

@skddc

This comment has been minimized.

skddc commented Oct 25, 2017

Yay, that worked! Thanks a lot!

@skddc skddc closed this Oct 25, 2017

@crccheck

This comment has been minimized.

crccheck commented Oct 30, 2017

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/

@RichardLitt RichardLitt reopened this Oct 30, 2017

@agjohnson

This comment has been minimized.

Contributor

agjohnson commented Oct 30, 2017

@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.

@agjohnson agjohnson closed this Oct 30, 2017

@crccheck

This comment has been minimized.

crccheck commented Oct 30, 2017

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

This comment has been minimized.

Contributor

agjohnson commented Oct 30, 2017

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

This comment has been minimized.

dselman commented Nov 30, 2017

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

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

@dselman

This comment has been minimized.

dselman commented Nov 30, 2017

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

This comment has been minimized.

Contributor

agjohnson commented Dec 4, 2017

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

@jwflory

This comment has been minimized.

jwflory commented Jan 18, 2018

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

This comment has been minimized.

jpic commented Mar 5, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment