Experiment: "Quickstart"-focused README

[ryan-williams]

It took me some digging to understand a few key things I needed for a Jupyterlite "Quickstart," where my use case was basically "put some notebooks on GitHub Pages, or other static site hosting, and have them be shareable and interactive (thanks to Jupyterlite)."

The minimal quickstart steps seem to be:

mkdir content && cp <some notebook>.ipynb content/
pip install jupyterlite jupyterlab
jupyter lite build --contents content --output-dir dist

At that point, dist/ is a static bundle that can be dropped anywhere, copied into an existing GitHub Pages site dir, etc.

The jupyterlab dependency was tricky to figure out. It's required for example notebooks to show up on the frontend. Otherwise, jupyter lite build --contents content will ≈silently fail to output api/contents/all.json (which is required for example notebooks from content/ to be presented to users, cf. jupyterlite/jupyterlite#318 (comment)).

Some other thoughts:

• deploy.yml in this repo is a good template for auto-publishing via GHA, which I know is somewhat described in this README, but took me a while to find+appreciate.
• Forking this repo to get an auto-published GitHub Pages site, with notebooks from contents/, is a powerful "Quickstart" that I didn't glean from my initial skim of relevant repos/docs.
• A lot of this info (like the existence and structure of this demo repo) could be called out more prominently in the main jupyterlite docs (and perhaps in an example notebook in this repo / the public demo site?). Something like how-to-host-your-own-jupyterlite.ipynb, easily findable in the main demo.

Anyway, I appreciate that the README.md in this repo is geared toward beginners; perhaps some of the above (and the README.md I wrote in this PR / my fork) could go in a quickstart.md or something?

Thoughts welcome, I'm not actually proposing to replace the README wholesale, this is just my take on explaining a quickstart to someone who's already more proficient with Git{,Hub}.

[ryan-williams]

I guess jupyterlite/jupyterlite#67 covers some of what I was trying to "fix"/document here. Also jupyterlite/jupyterlite#436

[jtpio]

Thanks @ryan-williams for suggesting this.

The JupyterLite documentation has been reworked, and there is now a getting started guide which should hopefully be clearer: https://jupyterlite.readthedocs.io/en/latest/quickstart/deploy.html

Do you think this addresses most of the points? Otherwise maybe you would like to consolidate it with further information? Thanks!

[ryan-williams]

That "deploy" page looks great, thanks! I'll close this now.

[jtpio]

Thanks again for your feedback, it was very valuable when iterating on the docs.

Feel free to update the documentation and open a PR if you would like to suggest more improvements, thanks!