Pants: Node "examples" documentation seems out of date?

[ns-cweber]

I was reading the "Examples" heading at the bottom of https://www.pantsbuild.org/node_readme.html, and it mentions examples in the "examples" directory, but when I skim https://github.com/pantsbuild/pants/tree/master/examples/, I don't see anything that looks like the examples mentioned in the docs. Am I looking in the wrong place? Did those examples move? Could the docs be updated to link to the specific examples to make it a little easier for users?

[jsirois]

Ah, yes. The node support is done in a "contrib" module. These are Pants plugins hosted by pants and you generally can know this is the case when you have to add a line like so in your pants.ini to use the plugin:

[GLOBAL]
plugins: [
    ''pantsbuild.pants.contrib.node==%(pants_version)s',',
  ]

In particular, all the contrib plugins ready for use outside the Pants project (some incubate a bit), are published to pypi as pantsbuild.pants.contrib.X.

So that doc comes from here: https://github.com/pantsbuild/pants/tree/master/contrib/node
It is unfortunate the generated html docs don't have the context of the link above.

[jsirois]

It does seem there is a bug or enhancement here in giving more context to the generated documentation, so I haven't closed the issue yet, but please let me know if the explanation above clears things up.

[jsirois]

Hmm, well there is this at the bottom of the page:

Generated by publish_docs from dist/markdown/html/contrib/node/README.html 2019-10-14T02:43:45.501929

That's small, gray, and even those obsucring bits aside, it's still not super clear where these docs live.

[ns-cweber]

Yes, that's very helpful, thank you for pointing me in the right direction. I think better docs would be a real boon for this project in terms of improving adoption. I don't know very much at this point (new to pants), but I'm paying attention as I learn so I can help other beginners.

[jsirois]

I think better docs would be a real boon for this project in terms of improving adoption.

I think we all concur!

[tommyk]

i created this repo with some examples as a reference for doing node stuff with pants, i don't know how good it is, but i got some things working after digging around in source code and what not. might be helpful to someone else coming across this issue.

https://github.com/tommyk/pants_node_example

[Eric-Arellano]

Thank you @tommyk! This is awesome!

You might be interested in joining the #v2node channel in our Slack (see https://pants.readme.io/docs/community). We have a user interested in redoing Node support to use the V2 engine, which brings much finer-grained caching and is far easier to write and extend.

It makes it easier to do things like add a custom Flow plugin, for example. The JS ecosystem is so big that we know the core Pants support will never cover it all, so extensibility is especially important.

We'd love your feedback on what is good and bad about this current implementation, and what you'd like to see in the rewrite! If you were interested, we would also be happy to pair with you on adding this support sooner.