There have been several issues opened #72, #86, #210, #270 regarding supporting multiple source (and test paths). @h13i32maru currently in March has declined to support this feature with the claim it is too complex for ESDoc, but my proof of concept implementation hopefully proves that it works fine while maintaining backward compatibility. It took ~20 minutes to get the first implementation working then ~3 hours to make it "bullet proof".
I have a test branch source-globs that seems to offer a great solution. Since I have done the proof of concept work in a branch of my fork of ESDoc which supports Babylon I'm posting a new issue here instead of a PR especially given that this is a potential major (but non-breaking) change.
I'd like to open comments in support of adding this feature into ESDoc and of course get any feedback on the implementation.
You can install it via:
npm install "git+https://[email protected]/typhonjs-node-esdoc/esdoc.git#source-globs"
Or including the above in package.json.
@h13i32maru I now have two major enhancements for ESDoc including the switch to Babylon parser and supporting multiple source / test globs which I'd like to upstream to ESDoc. Please consider accepting them! If you can agree to quickly review and accept PRs I'll certainly take the time to submit them! In my opinion after accepting these changes a new release 0.5 of ESDoc is pertinent.
The following is a description of the changes involved in the proof of concept.
I've included the glob npm module and treat config.source if it is an array then as an array of globs otherwise the string path is converted into an array with an all inclusive glob created from the string path as the single entry. Also ifconfig.test.source is an array it also is treated as an array of globs, etc.
So if you were to include three source paths the following config file applies:
{
"source": ["src/**/*.js", "src2/**/*.js", "src3/subdir/*.js"],
"destination": "docs"
}
It should be noted that config.source / config.test.source now holds an array of globs as a bare string path is converted into a glob and stored as the single entry in an array. There are two new config parameters which store the base working path for source and tests which are config.sourceDirPath and config.test.dirPath. To retain backward compatibility if either config.source or config.test.source is originally a path string then those paths define config.sourceDirPath and config.test.dirPath, but the user now has an option to override and provide in the config file config.sourceDirPath and config.test.dirPath which will be used in place instead of being generated. If not provided at all then they are set to the root path . when a source glob array is defined.
An example of including multiple paths relative to a user defined source directory path:
{
"source": ["otherpath/src/subdir1/**/*.js", "otherpath/src/subdir2/**/*.js", "otherpath/src/subdir3/**/*.js"],
"sourceDirPath": "otherpath/src",
"destination": "docs"
}
I added a basic sanity check in tests to just make sure things work with source glob arrays. I have tested this in a few separate repos and so far things work great for source and test loading for existing ESDoc config files and supporting the new source globs array pattern.
While two new config parameters are added (config.sourceDirPath and config.test.dirPath) they are not necessary to set in advance, so any existing ESDoc config file works as expected.
Impacts
With any major change it's important to consider the impact it might have on ESDoc plugins. As far as I'm aware I'm the only author of an ESDoc plugin, esdoc-plugin-jspm which uses the old hack of rewriting / synthesizing the config.includes regexp to include multiple source directories supporting JSPM managed source code. I don't believe any other existing ESDoc plugins may be impacted and supporting source globs is a much preferred direction for esdoc-plugin-jspm because it prevents usage of config.includes by overwriting it.
Given that a bare source path is rewritten to a source glob array and stored in config.source and config.test.source and the new config.sourceDirPath and config.test.dirPath entries contain the actual paths there is a potential for ESDoc plugins to be updated. This affects my plugin esdoc-plugin-enhanced-navigation, but has low impact. In that plugin I used the old config.source to rewrite file paths for the navigation. This can actually now be removed.
So, there may be a minor impact on a few ESDoc plugins, but the feature enhancement is much improved and since ESDoc is no where near v1.0 any affected plugins (if any at all outside my efforts) can easily make the change to use config.sourceDirPath as necessary.
Type: Feature Result: Reject Scope: Config
5.6k Jan 4, 2023
889 Dec 25, 2022
5.1k Jan 2, 2023
7.9k Jan 4, 2023
304 Sep 30, 2022
1k Dec 26, 2022
89 Jan 4, 2023
1.5k Nov 28, 2022
147 Dec 8, 2022
8 Nov 2, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
3 Jun 27, 2022
4 Dec 15, 2022
239 Dec 28, 2022
16 Aug 1, 2022
22 Aug 14, 2022
7 Nov 2, 2022
17.3k Jan 4, 2023