Recurse by default

[erikrose]

It might be nice to find JS files deeper than at the root of the source directory. To so do, pass -r to jsdoc. However, that also searches within any node_modules dir, which is bad, because that's huge and irrelevant. We can exclude node_modules using a jsdoc config file.

Thus, the way to go about this is probably to include a jsdoc conf file inside sphinx-js and point to it. Set up the exclusion and say recurse:true within it.

People who want to provide their own jsdoc config files should start with a copy of ours and can control their own recursion preferences.

[rgammans]

I'm not sure 'recurse:true' works. I can't find and documentation which suggests that it does. This config file { "recurse": true, "recurseDepth": 10 } run with jsdoc $JS_ROOT_PATH -c doc/source/jsdoc.json does not seem to recurse where as jsdoc $JS_ROOT_PATH -r does

At least this seems to be the case with jsdoc 3.5.3

I'd go as far to suggest that not recursing as default is bug; because you have documented sub paths in the README, but without any comments about this.

Would you accept a PR to add -r to the js command line on the basis of a new sphinx level config option?
(In my case the node_modules directory is outside $JS_ROOT_PATH anyway)

[erikrose]

This config file works, as simplified from my link in the original ticket description:

{
    "opts": {
        "recurse": true
    }
}

(You have to wrap opts around the whole thing. Tested it just now with 3.4.3.)

I brought up the config file because it is the only way atm to exclude paths (like node_modules).

[erikrose]

I lean toward recursion being the default as well, as long as we also avoid node_modules by default. My goals are:

1. Ease of use (and lack of surprise) for common scenarios
2. Not having to support a corresponding Sphinx config option for every (now and future) jsdoc option
3. The ability to use arbitrary jsdoc config options

I propose to have sphinx-js by default use a config file within itself that recurses and skips node_modules. If someone wants to disable recursion or do something else fancy, they can provide their own jsdoc config file and use jsdoc_config_path. What do you think of that? I'd gladly accept a PR in that direction. We can then figure out whether to consider that a backward-incompatible change worthy of a major-version rev or not. :-)