Docs: jsdoc example using build.jobs and build.tools

[humitos]

Expand our build customization page with an example for jsdoc.

See https://test-builds.readthedocs.io/en/jsdoc/ as example of usage.

[ericholscher]

Seems like this is missing the part where you actually implement it in Sphinx? Could be neat to include to make it more copy-pastable.

[humitos]

Ah, yeah. I wasn't sure if this page is the right place for that. I felt that I was contaminating it with a lot of code that it's outside the scope of build.jobs / build customization. Probably, the full example fits better on a blog post or a guide explaining the full process to document Javascript documentation. We could link to that post/guide from here.

[agjohnson]

Yeah, agreed, I'd probably rather have a guide for this. It's fairly common to use sphinx-js for this, which is possible to use without build commands even:

https://github.com/readthedocs/ext-theme/blob/main/.readthedocs.yaml
https://github.com/readthedocs/ext-theme/blob/main/docs/conf.py

There's additional caveats, like needing a supported version of jsdoc/typedoc. And also how to write documentation and configure jsdoc to document a source tree of JS files is probably the largest point of that guide. I think everything in one place is probably the most approachable format for a guide like this.

[agjohnson]

Also, if we can generalize this example, maybe it's wise to point out npm ci as well. This is probably what the user wants ultimately, for reproducible builds, so would be a good suggestion for us to give.

Suggested change

	- npm install -g jsdoc
	- npm ci
	- npm install -g jsdoc

[agjohnson]

Perhaps this is better off just as a generalized example. There is a lot to say about actually using sphinx-js and jsdoc together, especially once you get past a basic example and on to documenting a full JS library.

I've wanted to write up a more complete guide around this. Perhaps this guide should be my doc addition focus one of the next sprints. I found the sphinx-js docs not super helpful, and struggled with a few configuration pieces to make everything work.

[agjohnson]

This might be better off generalized, rather than specific to jsdoc. There is a lot more to say about jsdoc usage, and duplicating that here will probably guide users to the wrong guide content.

Suggested change

	Document your code with ``jsdoc``
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	Install Node.js dependencies
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[humitos]

I like this idea, 💯

[agjohnson]

If generalizing this, the copy here would need to be tweaked. But generally, noting to use the official terminology:

Suggested change

	To setup it, you need to first define the version of ``nodejs`` you want to use and also install ``jsdoc`` as shown below:
	To setup it, you need to first define the version of Node.js you want to use and also install ``jsdoc`` as shown below:

[agjohnson]

Also, if we can generalize this example, maybe it's wise to point out npm ci as well. This is probably what the user wants ultimately, for reproducible builds, so would be a good suggestion for us to give.

Suggested change

	- npm install -g jsdoc
	- npm ci
	- npm install -g jsdoc

[humitos]

Thanks for the feedback on this. I will update the documentation to make it more generalized as Anthony suggested. I think that's the right step. After that, we can write a guide / post for a specific use case of this feature together with jsdoc 👍🏼

[humitos]

I updated the PR to make it more generalized, and I like it more. Let me know if it's ready to merge.

I also opened #9247 to track the writing of a blog post / guide for jsdoc.

[agjohnson]

💯

[ericholscher]

Will be curious to see if we get any SEO traffic for this page 🤔