Skip to content

Refine docker-vs-jupyter framing, de-emphasize legacy endpoints, expand kernels for training content - #591

Merged
dfguerrerom merged 2 commits into
mainfrom
developers-section-revisions
May 29, 2026
Merged

Refine docker-vs-jupyter framing, de-emphasize legacy endpoints, expand kernels for training content#591
dfguerrerom merged 2 commits into
mainfrom
developers-section-revisions

Conversation

@dfguerrerom

Copy link
Copy Markdown
Collaborator

Follow-up review on the developers section merged in #590.

What this changes

app_types.rst — bigger restructure

  • Legacy endpoints called out: shiny is no longer recommended for new apps; rstudio is reserved for the built-in tool. A note at the top says so plainly.
  • "At a glance" table reworked around the distinction developers actually care about:
    • Docker apps run on the shared SEPAL server (one instance backs every user).
    • Jupyter apps run inside each user's own SEPAL instance, so compute scales with what the user provisions.
  • Code location row clarifies that both endpoints clone from repository; only the destination differs (container vs /home/sepal-user/shared/apps/<app>/).
  • Isolation row drops the misleading "optional packaged kernel" — for jupyter apps the micromamba kernel from sepal_environment.yml is the rule.
  • Lifecycle row renamed to Update trigger and reframed: both endpoints update independently of sandbox restarts; what differs is whether the trigger is a catalog commit bump or a branch-tip push.
  • Expanded narrative sections explain the resource model (shared single backend vs per-user instance compute).
  • New "When to use which" rule-of-thumb table.

app_catalog.rst

  • Endpoint row notes that only jupyter / docker are recommended for new apps.
  • Drops the shiny variant from the path description.
  • Lead paragraph drops "jupyter and shiny" in favor of "jupyter".

releases.rst

  • Drops shiny from the per-endpoint breakdown and the section heading.
  • Adds the .. _developers_apps_releases_branch: label so other pages can link the release-branch convention.

kernels.rst

  • The "same PR flow / same release lifecycle" sentence now hyperlinks to app_catalog and the jupyter sub-section of releases.
  • New section: "Ship notebooks and data alongside the kernel" — explains that the same clone the app-manager uses lands at /home/sepal-user/shared/apps/<app>/ on every user's sandbox, so the same mechanism is also the right way to ship training notebooks and supporting data to a cohort. Covers practical conventions (top-level notebooks, keep large data external, tag a release branch per cohort).

apps/index.rst

  • Drops "shiny" from the catalog-role note.

Verification

nox -s docs — green, zero warnings.
nox -s lint — black, ruff, prettier, doc8, codespell all pass.

…nd kernels for training content

Iteration on the developers section in response to review feedback:

app_types.rst
- New legacy note: shiny is no longer recommended for new apps;
  rstudio is reserved for the built-in tool.
- "At a glance" table reworked around the real distinction
  developers care about: docker runs on the shared SEPAL server (one
  instance for all users), jupyter runs inside each user's own
  sandbox (compute scales with what the user provisions).
- Code location row clarifies that both endpoints clone from
  repository; only the destination differs (container vs
  /home/sepal-user/shared/apps/<app>/).
- Isolation row drops "optional packaged kernel" — for jupyter
  apps the micromamba kernel built from sepal_environment.yml is
  the rule, not the exception.
- Lifecycle row renamed to "Update trigger" and reframed: both
  update independently of the sandbox; what differs is whether the
  trigger is a catalog commit bump or a branch-tip push.
- Expanded "Docker apps" and "Jupyter apps" sections to spell
  out the resource model (shared single backend vs per-user
  instance compute).
- New "When to use which" rule-of-thumb table at the bottom.

app_catalog.rst
- Endpoint row notes only jupyter/docker for new apps.
- path row drops the shiny variant.
- Lead paragraph drops "jupyter and shiny" in favor of
  "jupyter".

releases.rst
- Drops shiny from the per-endpoint breakdown and the heading.
- Adds .. _developers_apps_releases_branch: label so other pages
  can link the release-branch convention.

kernels.rst
- "Same PR flow / release lifecycle" sentence now hyperlinks
  to app_catalog and releases (jupyter sub-section).
- New "Ship notebooks and data alongside the kernel" section:
  the cloned repo lands under /home/sepal-user/shared/apps/<app>/
  on every user's sandbox, so the same mechanism is also how to
  ship training notebooks and small data alongside the env.

apps/index.rst
- Drops "shiny" from the catalog-role note.
- "Who pays for compute" -> "Where compute happens" (SEPAL funds
  both runtimes — the distinction is location, not who pays).
- Docker update trigger is the app-launcher checking out the new
  commit at launch time, not the app-manager.
@dfguerrerom
dfguerrerom merged commit 71b5dc3 into main May 29, 2026
3 checks passed
@dfguerrerom
dfguerrerom deleted the developers-section-revisions branch May 29, 2026 09:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant