Skip to content
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
raucao opened this issue Aug 28, 2017 · 20 comments
Closed

Add JSDoc to docs build environment #3069

raucao opened this issue Aug 28, 2017 · 20 comments

Comments

@raucao
Copy link

@raucao raucao 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
Copy link

@wmnnd 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
Copy link
Contributor

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

@raucao
Copy link
Author

@raucao raucao commented Sep 22, 2017

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

@excitedleigh
Copy link

@excitedleigh excitedleigh 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?

@raucao
Copy link
Author

@raucao raucao commented Oct 2, 2017

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

@raucao
Copy link
Author

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

@raucao
Copy link
Author

@raucao raucao 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
Copy link
Contributor

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

@raucao
Copy link
Author

@raucao raucao 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
Copy link
Contributor

@agjohnson agjohnson commented Oct 25, 2017

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

@raucao
Copy link
Author

@raucao raucao commented Oct 25, 2017

Yay, that worked! Thanks a lot!

@raucao raucao closed this Oct 25, 2017
@crccheck
Copy link

@crccheck 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
Copy link
Contributor

@agjohnson 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
Copy link

@crccheck 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
Copy link
Contributor

@agjohnson 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
Copy link

@dselman dselman commented Nov 30, 2017

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
Copy link

@dselman 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
Copy link
Contributor

@agjohnson 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
Copy link

@jwflory 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
Copy link

@jpic 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
9 participants