Support custom babel config #1205

dougalg · 2019-02-13T06:55:35Z

Proposal:

Allow users to support their own babel configuration via new cli option:

documentation build --babel=./babel.config.js

Aims to resolve: #1149, #140

This will need some refinement of implementation, but if the overall concept is acceptable, that should be easy to resolve.

dougalg · 2019-02-13T06:57:04Z

src/input/dependency.js

@@ -17,6 +46,9 @@ const smartGlob = require('../smart_glob.js');
 * @returns results
 */
 function dependencyStream(indexes, config) {
+  const babelConfig = config.babel
+    ? { configFile: path.resolve(__dirname, '../../../../', config.babel) }


Idea here is to load the config relative to wherever documentation was installed.

might be easier to manage as an absolute path

dougalg · 2019-02-21T05:45:30Z

@tmcw any thoughts on this?

tmcw · 2019-02-21T05:55:59Z

This looks great! The only thing I'm not sure about is the ../../../ with __dirname - seems a little iffy, especially if documentation.js is installed globally. Maybe using process.cwd(), when someone uses the CLI, at least, would be more predictable?

bj00rn · 2019-02-21T10:43:46Z

👍 for this! 👍

bj00rn · 2019-02-21T11:56:27Z

This looks great! The only thing I'm not sure about is the ../../../ with __dirname - seems a little iffy, especially if documentation.js is installed globally. Maybe using process.cwd(), when someone uses the CLI, at least, would be more predictable?

@tmcw, @dougalg agree, can we use an absolute path in the mean time perhaps?

bj00rn · 2019-02-21T12:12:05Z

fixes issue in #996

kevinmartin · 2019-03-04T16:46:00Z

Maybe @babel/core and @babel/parser should be placed as peer dependencies. I'm personally using a newer version of Babel on my end that isn't compatible with the ones Documentation.js is requesting.

tmcw · 2019-03-12T18:48:40Z

Okay, going to merge and release a 10.x pre release so folks can test it out.

BREAKING CHANGE: this may change babel configuration loading, and is a major change to the documentation.js approach to Babel.

tmcw · 2019-03-12T18:54:44Z

Published as 10.0.0-alpha.0 - please try it out and make sure this does what everyone intends, and then I'll tag a 10.0.0!

tmcw · 2019-03-12T18:58:08Z

@kevinmartin the babel dependencies of documentation.js are all specified as ^7 series. There isn't an 8 series, yet, so I'm not sure how you can be using something that's newer.

kopax · 2019-03-12T19:15:02Z

Hi! How does this resolve #1149?
Am I now able somehow to build documentation jsdoc when files use webpack import()?

kopax · 2019-04-01T15:39:05Z

I have tried and it does not solve #1149.

I also tried to add --babel=./babel.config.js but that did not helped:

 npx documentation build 'src/**' -f md -o foobar --babel=./babel.config.js
Unknown argument: babel

tmcw · 2019-04-01T17:02:36Z

I published this as a prerelease (an alpha), so npx will not install 10.0.0-alpha.0. If you want to test the alpha release, you'll need to specify documentation@10.0.0-alpha.0

kopax · 2019-04-02T09:29:52Z

Oh ok that make sens. Any plan for the final release? Will the --babel option be able to auto configure?

tmcw · 2019-04-11T16:08:46Z

Final release is mostly pending a few folks (it could be you!) installing the alpha and confirming that it does what you expect.

kopax · 2019-04-11T17:08:15Z

@tmcw oh sorry, I didn't make it a priority but I didn't know it was waiting for testers. I am still surprised that we need a --babel option. Couldn't we pick it up automatically by default or use a --auto? Why not? We needed a generic way of building doc and this will require some extra tuning on our side. I'll have a try as soon as I understand how we should deal with the new api.

amidf · 2019-04-11T19:25:29Z

@tmcw I agree with @kopax. I just need a cool documentation generator which will work from scratch with all my code. And I, for example, don't want to manage with babel configs. They are terrible :)

tmcw · 2019-04-11T19:58:17Z

Can you at least try installing the alpha using the --babel option first? This is a community project: doug did the work of building this feature, please do the work of testing it. Without summarizing the entire landscape of JavaScript, there are reasons why documentation.js is unable to parse every potential variation of the language out of the box, because there are infinite variations.

kopax · 2019-04-12T05:32:21Z

@tmcw of course, sorry to have those extra questions personal to my use case.

I went through tests and I can confirm @dougalg implementation is working on the 3 projects I got it tested.

I have found one potential issue if people use package.json for storing their babel configuration:

ReferenceError: Unknown option: .name. Check out https://babeljs.io/docs/en/babel-core/#options for more information about options. while parsing file: src/index.js

This means that we cannot use --babel package.json even if it's a proper way to store the babel configuration

there are reasons why documentation.js is unable to parse every potential variation of the language out of the box, because there are infinite variations.

This is surprising me, we generally have one babel configuration per project, located in .babelrc, babel.config.js, or package.json. This file contains all you need to know before using any of the sources, even for typescript.

I am quite aware of the javascript ecosystem, what did I miss that tells you that we cannot support a default --auto feature without pain?

My concern is that without this automation, we will have to wrap the command and do something like this in our script:

babel_config=(babel.config.js .babelrc package.json)
args=""
for cfg in "${babel_config[@]}"; do
  if [[ -f $cfg ]]; then
    if [[ $cfg != package.json ]]; then
      args="$args --babel $cfg"
    else
      res=$(cat $cfg | jq .babel)
      ## or without jq: res=$(cat $cfg | grep '"babel": ')
      ## Fail, but it can be fixed by extracting the babel configuration into a temporary file
      [[ -n $res ]] && args="$args --babel $cfg" 
    fi
  fi
done

documentation build 'src/**/*.js' -f md -o test.md "$args"

dougalg · 2019-04-12T08:24:41Z

@tmcw @kopax somehow I missed all this discussion, I had totally forgotten this PR, so sorry! Thanks for merging it, I'm glad I helped.

I think the ideal solution is rather than passing a babel path allow a --babel-local option or similar where babel can do a lookup in the standard manner from the project root to find the config.

It actually looks like maybe babelify can be given a correct root option from which to locate babelrc, babel.config, etc using Babel's native config loader. IMO this would be a better option than trying to manage that ourselves in this project.

goodmind · 2019-04-26T02:46:13Z

Does this support custom parser options?

kopax · 2019-04-26T11:43:23Z

@goodmind I think this was never released.

@dougalg I get all your point will you take care of the case? Otherwise just so you know, the branch you were working on as been deleted.

tmcw · 2019-04-26T16:42:20Z

The babel option was released as part of 10.0.0, and is included in later releases, as detailed in the changelog.

kopax · 2019-04-27T16:21:09Z

Sorry I didn't noticed it was released.

People should be aware that it may break in the futur (except if we support both option)

@dougalg, will you take care of the --babel-local?

It actually looks like maybe babelify can be given a correct root option from which to locate babelrc, babel.config, etc using Babel's native config loader. IMO this would be a better option than trying to manage that ourselves in this project.

Perhaps if I understand the concerned module and documentation I should read, I may try to help implement the feature.

dougalg · 2019-05-07T03:37:03Z

@kopax for some reason I'm not getting email notifications about discussion here. Good thing I checked back in. I don't have time at the moment, but maybe in a month or so. Regardless the existing version was merged for now, which is still a step forward.

When I have time, I would like to come back to this if someone else does not take it on first.

candu · 2019-09-11T13:54:31Z

Has anyone managed to get Babel config working with documentation lint?

Support custom babel config

e680cd7

dougalg commented Feb 13, 2019

View reviewed changes

tmcw merged commit 4629a47 into documentationjs:master Mar 12, 2019

tmcw pushed a commit that referenced this pull request Mar 12, 2019

feat: Support custom babel config (#1205)

746d0a9

BREAKING CHANGE: this may change babel configuration loading, and is a major change to the documentation.js approach to Babel.

kopax mentioned this pull request Apr 1, 2019

Parse error (unexpected token) on dynamic import #1149

Closed

dougalg deleted the babel branch April 12, 2019 08:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support custom babel config #1205

Support custom babel config #1205

dougalg commented Feb 13, 2019 •

edited

Loading

dougalg Feb 13, 2019

dougalg Feb 13, 2019

dougalg commented Feb 21, 2019

tmcw commented Feb 21, 2019

bj00rn commented Feb 21, 2019 •

edited

Loading

bj00rn commented Feb 21, 2019

bj00rn commented Feb 21, 2019 •

edited

Loading

kevinmartin commented Mar 4, 2019

tmcw commented Mar 12, 2019

tmcw commented Mar 12, 2019

tmcw commented Mar 12, 2019

kopax commented Mar 12, 2019

kopax commented Apr 1, 2019 •

edited

Loading

tmcw commented Apr 1, 2019

kopax commented Apr 2, 2019

tmcw commented Apr 11, 2019

kopax commented Apr 11, 2019 •

edited

Loading

amidf commented Apr 11, 2019

tmcw commented Apr 11, 2019

kopax commented Apr 12, 2019 •

edited

Loading

dougalg commented Apr 12, 2019

goodmind commented Apr 26, 2019

kopax commented Apr 26, 2019

tmcw commented Apr 26, 2019

kopax commented Apr 27, 2019

dougalg commented May 7, 2019

candu commented Sep 11, 2019

Support custom babel config #1205

Support custom babel config #1205

Conversation

dougalg commented Feb 13, 2019 • edited Loading

dougalg Feb 13, 2019

Choose a reason for hiding this comment

dougalg Feb 13, 2019

Choose a reason for hiding this comment

dougalg commented Feb 21, 2019

tmcw commented Feb 21, 2019

bj00rn commented Feb 21, 2019 • edited Loading

bj00rn commented Feb 21, 2019

bj00rn commented Feb 21, 2019 • edited Loading

kevinmartin commented Mar 4, 2019

tmcw commented Mar 12, 2019

tmcw commented Mar 12, 2019

tmcw commented Mar 12, 2019

kopax commented Mar 12, 2019

kopax commented Apr 1, 2019 • edited Loading

tmcw commented Apr 1, 2019

kopax commented Apr 2, 2019

tmcw commented Apr 11, 2019

kopax commented Apr 11, 2019 • edited Loading

amidf commented Apr 11, 2019

tmcw commented Apr 11, 2019

kopax commented Apr 12, 2019 • edited Loading

dougalg commented Apr 12, 2019

goodmind commented Apr 26, 2019

kopax commented Apr 26, 2019

tmcw commented Apr 26, 2019

kopax commented Apr 27, 2019

dougalg commented May 7, 2019

candu commented Sep 11, 2019

dougalg commented Feb 13, 2019 •

edited

Loading

bj00rn commented Feb 21, 2019 •

edited

Loading

bj00rn commented Feb 21, 2019 •

edited

Loading

kopax commented Apr 1, 2019 •

edited

Loading

kopax commented Apr 11, 2019 •

edited

Loading

kopax commented Apr 12, 2019 •

edited

Loading