[ENH] - Clarify the purpose and access to the examples folder

[kcpevey]

Context

When explaining access to the shared folder to new users, I say something like:

"The shared folder contains subfolders, one for each user group. Each user can only see and access the subfolder for the user group(s) that they are in."

but then... there is this shared/examples folder.

"The examples folder isn't a user group, it just has examples. But no one (?) can add or take away from it, it's just there."

That story feels off.

I propose a few options to help smooth this over.

• The examples folder could be a read-only folder that everyone sees off of root (similar to shared).
• The examples folder could be renamed to something explicit like: examples-READONLY
• The examples folder (and the shared folder for that matter) could contain a README.txt file explaining its purpose and the fact that its read only. (I'd suggest doing this as an absolute minimum)

Value and/or benefit

Less confused users.

Anything else?

No response

[iameskild]

What if we cloned the nebari-demo in the examples folder instead? We might need to just clean it up a bit and migrate the kbatch examples we currently have.

cc @pavithraes @trallard?

[trallard]

Stepping back - what is the purpose or added value of adding these examples on every nebari instance and thus for all users?
Is the existence of said examples necessary for anyone to use nebari or any of its components at all? - answer: no

The examples in shared/examples are all pretty basic ("hello world" style) examples. And
IMHO they are not essential to have there to start with - I would prefer having all the tutorial-like materials either in our docs or in repositories like nebari-demo.
This will result in a better user experience and help us with maintainability instead of having multiple places where examples/tutorials/intro live and need to be updated.

The examples folder could be a read-only folder that everyone sees off of root (similar to shared).

In my opinion, this would make for a terrible user experience.
As a platform user, unless there is anything critical to nebari itself and/or that would cause major problems if I delete it, I do not want a random folder with things in it in my day-to-day platform.
We'd be forcing anyone on nebari to keep around low-value examples to avoid confusion around something where our implementation was a tad flaky (in the sense that this folder does not fit our permissions model, but it is just there 🤷🏽)

[kcpevey]

I agree with everything you said @trallard. I think we'd be better served if it just went away altogether.

I also like the idea of an examples repo with notebooks that users can run. Perhaps then we can provide people with an nbgitpuller link to quickly pull the repo into their workspace if they choose.

[kcpevey]

what if we added a button/link to the Launcher page that was an nbgitpuller link to an examples repo?

[kcpevey]

And to be clear, I'm thinking about providing our tutorials as notebooks (which we can link to at the end of each docs page). This creates maintenance burden, but it would streamline things for users.

[kcpevey]

Current plan:

1. Make sure that all the examples in the examples folder are covered by tutorials and provided as notebooks in https://github.com/nebari-dev/nebari-demo
2. remove the examples folder entirely

Notes:

• the kbatch tutorial in the docs isnt working (the job just hangs). I'm told the examples folder kbatch stuff works - we need to confirm that and update the tutorial.
• dashboards - we have a panel tutorial that walks through CDS dashboards usage but we need to find better examples for the remaining frameworks. These frameworks host example repos and I'm considering just adding them as a submodule in nebari-demo.
  • I'm thinking https://github.com/plotly/dash-sample-apps/tree/main/apps/dash-oil-and-gas for plotly-dash and https://github.com/jkanner/streamlit-dataview for streamlit. Still need to find one for voila

[kcpevey]

Related to dashboards docs: nebari-dev/nebari-docs#239 and nebari-dev/nebari-docs#242

[kcpevey]

kbatch examples can be removed since the docs have been updated (nebari-dev/nebari-docs#260)

[viniciusdc]

Some comments I added to another issue (duplicated)

We are currently reaching a point where some limitations of the current approach we were using for storing the examples on nebari. Some of the drawbacks:

• As we build that folder by using configmaps on Kubernetes, we are reaching the 1MB limit of files that such a structure can support
• The main idea for those examples was initially thought of as a first glance at each one of the services that Nebari supports. While they help with CI testing, they only provide enough guidance to new users on working with the tool if they have prior experience.

Some options that we discussed range in between these points:

• using jlab links to access and download the necessary repo containing the demo files would help us remove the need for the examples to be built (and stored in the code-base) at all.
• Using some jupyterlab hub page where you can search for the available demos and download the files as needed by pressing a button (e.g using iframe)

[kcpevey]

All of the examples in the shared example folder have been added to the nebari-demo repo and the environments have been updated. We can now removed the examples folder itself.