Getting Started Docs

[psychemedia]

Are there any really simple Getting Started docs?

I'm guess the minimum is something along the lines of:

• run cookie cutter to generate example package;
• pip install . then wait for the build to complete...
• load JupyterLab (visit localhost:8888/lab in your browser)
• check the console (loaded from browser developer tools) for the message JupyterLab extension YOUR_EXTENSION_NAME is activated!

[welcome]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively.

You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[jtpio]

Thanks @psychemedia for raising this.

There should be some basic dev instructions in https://github.com/jupyterlab/extension-cookiecutter-js/tree/master/%7B%7Bcookiecutter.python_name%7D%7D#development-install, which of course can be improved.

For now there has been more work and energy put on the TypeScript cookiecutter: https://github.com/jupyterlab/extension-cookiecutter-ts and the JS cookiecutter follows pretty much the same structure.

There is also a tutorial in the JupyterLab documentation: https://jupyterlab.readthedocs.io/en/stable/extension/extension_tutorial.html, so maybe there could be a link to it here in the cookiecutter repo?

[krassowski]

The extension tutorial is typescript heavy though. For some context, I think that this issue follows from previous discussion in replies to https://twitter.com/psychemedia/status/1412414352318140419. I do agree that it can be difficult to wrap one's head around the increasingly complex typescript version of the cookiecutter:

js cookeicutter used to be much easier to understand but it also got a few more files (Python files!) to allow creating prebuilt extensions:

If we want to keep updating and possibly expanding the ts version as needed to ensure we have a best-practice for extensions development there, should keep a minimal js-only starting docs "for tinkerers" here?

Also see https://twitter.com/choldgraf/status/1412687806414139394 for some discussion on another platform (CC @choldgraf).

[jtpio]

Ah right, thanks @krassowski for the extra context.

Maybe we should open a thread on Discourse to discuss this. Or an issue in the JupyterLab repo.

I totally agree there should be a way to more easily prototype simple extensions from within lab itself with having to setup complex toolchains locally. Especially since this should now be easier to implement with the new system of prebuilt extensions (iirc this was also briefly discussed on Twitter).

[choldgraf]

I'd recommend reading through @evildmp's Diataxis guide on Tutorials for inspiration about this set of docs. I'm reminded of some language in there suggesting that tutorials should not have any extraneous information other than what is absolutely necessary to accomplish the goal of the tutorial. So if the tutorial is about "creating your first JupyterLab extension", then I guess the question would be "is TypeScript (or any more complex thing) absolutely necessary to accomplish this?" (same goes for any other kind of tool like prettier). If not, then that information is simply going to add extra things for the learner to remember and understand.

[psychemedia]

@choldgraf +1 on the keep extraneous information out; every file in a demo repo will cause a novice to wonder and worry about what it does, under the assumption that it's vital for it to be there (it would be really interesting to see how many "superstitious" files are included in Github repos from folk who initially cloned the repo from another one, generated it from a cookiecutter, etc etc.;-). A confusion of files can also be a blocker to folk who might be able and willing to support the documentation effort if they thought they could understand things well enough to help contribute editorial effort to the docs.

Having a brief comment at the top of each file to briefly describe what it does can also be useful. A separate manifest detailing the files that you MUST have for the demo to work and COULD have eg to smooth development, can be useful on the occasion of someone deleting a load of files and then wondering why things have broken and how to get it working again.

[jtpio]

As mentioned in jupyterlab/jupyterlab#11075 (comment):

And we continue providing two cookiecutters, with slightly different goals:

* TypeScript cookiecutter: full-blown cookiecutter with all the files like it is now (to ensure best practices)

* JavaScript cookiecutter: only the files required to develop the prebuilt extension. The initial script could do the symlinking like when developing notebook extensions. Then ideally editing the JavaScript source would not need a new rebuild of the webpack federated module (to be confirmed)

Maybe a good way forward would be to simplify this JavaScript cookiecutter and stick to the minimal amount of files for writing an extension in JavaScript.