Add doc on jupyterlab-gallery #528

kcpevey · 2024-09-24T19:26:58Z

We've had several requests for a formalized walkthrough of JupyterLab-Gallery. This PR adds a how to explaining things to users.

Reference Issues or PRs

What does this implement/fix?

Put a x in the boxes that apply

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds a feature)
Breaking change (fix or feature that would cause existing features not to work as expected)
Documentation Update
Code style update (formatting, renaming)
Refactoring (no functional changes, no API changes)
Build related changes
Other (please describe):

Testing

Did you test the pull request locally?
Did you add new tests?

Documentation

Access-centered content checklist

Text styling

The content is written with plain language (where relevant).
If there are headers, they use the proper header tags (with only one level-one header: H1 or # in markdown).
All links describe where they link to (for example, check the Nebari website).
This content adheres to the Nebari style guides.

Non-text content

All content is represented as text (for example, images need alt text, and videos need captions or descriptive transcripts).
If there are emojis, there are not more than three in a row.
Don't use flashing GIFs or videos.
If the content were to be read as plain text, it still makes sense, and no information is missing.

Any other comments?

netlify · 2024-09-24T19:27:12Z

✅ Deploy Preview for nebari-docs ready!

Name	Link
🔨 Latest commit	`96db8a4`
🔍 Latest deploy log	https://app.netlify.com/projects/nebari-docs/deploys/685c6a252c265300086525b4
😎 Deploy Preview	https://deploy-preview-528--nebari-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

kcpevey · 2024-09-24T19:45:39Z

docs/docs/how-tos/jupyter-gallery.md

+| ----------- | ---------------------------------------------------------------------------- |
+| title       | Title on the gallery tile                                                    |
+| git         | URL of the git repository                                                    |
+| homepage    | (Optional)                                                                   |


I'm not sure what this is?

Can be used as a link to the examples repository. The idea is to separate the git URL which might contain token (discouraged) from the link shown in the UI (if any).

This is also used to generate fallback icon from GitHub social cards

Can be used as a link to the examples repository.

As far as I can tell, the UI doesn't link to the repository in any way. If I hover the gallery tile, I just have the options to download or go to the folder. Is this link provided to the users somewhere else?

That's correct, it is not available in the UI. For god security practice the git URL is separated from user facing URL even though it is not currently in the UI. My plan was to add a new button with link icon but I guess it is low priority. It would be rather low effort too though.

kcpevey · 2024-09-24T19:45:47Z

docs/docs/how-tos/jupyter-gallery.md

+| homepage    | (Optional)                                                                   |
+| description | Description of the repository to appear on the gallery tile (Optional)       |
+| icon        | base64 encoded image to use an icon to appear on the gallery tile (Optional) |
+| account     | (Optional)                                                                   |


Not sure what this is?

When you log in using token you need to also pass account. Depending on whether it is GitHub or GitLab it should be a pre-defined string, or any string.

This is defined in https://github.com/nebari-dev/jupyterlab-gallery/blob/ef56fc616bae4ec8305c01e3341b773ca4cfd48f/jupyterlab_gallery/manager.py#L30-L82

You can access the documentation via jupyterlab-gallery --help-all. I will add it to the README.

@krassowski for account, what does that look like in a github and gitlab url?

For example, if I go to "clone from https" on the nebari-dev repo, it gives this url: https://github.com/nebari-dev/nebari.git . Would the account be nebari-dev or is that my username associate with the token?

For gitlab the "clone from https" could looks like this: https://gitlab.<domain>.net/<projectname>/<teamname>/gradient.git. What is the account here?

It is not a part of the URL. It is used during login sequence, the same way as you would login via CLI when issuing say git push on a new machine (by providing a user name and password). Of course you would not because everyone has an SSH key configured instead.

See the example at the bottom of https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#using-a-personal-access-token-on-the-command-line

docs/docs/how-tos/jupyter-gallery.md

krassowski

What should we do with https://www.nebari.dev/docs/explanations/custom-overrides-configuration#jupyterlab? It includes some important warnings about the PAT/token usage, and feels like a right place to at least keep a mention of gallery_settings. Should it link to this how-to?

docs/docs/how-tos/jupyter-gallery.md

krassowski · 2024-09-25T18:35:44Z

docs/docs/how-tos/jupyter-gallery.md

+Several repositories can be configured to display as individual gallery tiles. Under the `exhibits`
+section, each repository must have a `title` and a `git` location. There are also several other
+optional config options.


Just a note: currently the tiles are designed so that they are most beautiful when there is a description. I would personally say that adding description is recommended, but do not want to push it either.

docs/docs/how-tos/jupyter-gallery.md

viniciusdc · 2024-11-01T14:18:19Z

@kcpevey @krassowski what's the current status on this? I recently needed this information and relied on the preview here hshshs. Is there anything I can help with? Also, I think the part regarding the use of tokens needs a bit more explanation I primarily relied on the repo readme, the discussions above and actual deployments to grasp what was happening in terms of auth fully.

Also, I note that how the extension identifies new commits would be helpful since I was not sure how it would update the clones until I tested it myself. Overall, this tool is fantastic! Huge shout out @krassowski !

docs/docs/how-tos/jupyter-gallery.md

Co-authored-by: Michał Krassowski <[email protected]>

viniciusdc

LGTM, I will merge this PR so that we have at least a bit more information about this tool, since its been included in nebari since a few versions ago. I will open a follow up issue to read trough all the contents and suggest changes as needed.

add doc on jupyter gallery

2f54938

Kim Pevey added 2 commits September 24, 2024 14:28

fix my inability to spell

c10f6b9

yarn linter

a495364

kcpevey requested a review from krassowski September 24, 2024 19:41

kcpevey commented Sep 24, 2024

View reviewed changes

docs/docs/how-tos/jupyter-gallery.md Outdated Show resolved Hide resolved

krassowski reviewed Sep 25, 2024

View reviewed changes

fix token description, add cross references jupyterlab overrides section

eab3757

krassowski reviewed Nov 1, 2024

View reviewed changes

docs/docs/how-tos/jupyter-gallery.md Outdated Show resolved Hide resolved

krassowski and others added 7 commits January 9, 2025 12:26

Fix typo

62f0f81

Merge branch 'main' into jupyter-gallery

7bd1374

fix lint typo

92fc0ae

Merge branch 'main' into jupyter-gallery

b188378

yarn run format --write

252fcfe

Apply suggestions from code review

4b8e6b8

Co-authored-by: Michał Krassowski <[email protected]>

run format

96db8a4

viniciusdc approved these changes Jun 25, 2025

View reviewed changes

viniciusdc merged commit 702fa70 into main Jun 25, 2025
6 checks passed

viniciusdc deleted the jupyter-gallery branch June 25, 2025 22:23

github-project-automation bot moved this from Todo 📬 to Done 💪🏾 in 📖 - Documentation Jun 25, 2025

viniciusdc mentioned this pull request Jun 25, 2025

[DOC] - Review current docs on how to use and configure jupyter-galery #586

Open

1 task

Add doc on jupyterlab-gallery #528

Add doc on jupyterlab-gallery #528

Uh oh!

Conversation

kcpevey commented Sep 24, 2024

Reference Issues or PRs

What does this implement/fix?

Testing

Documentation

Access-centered content checklist

Text styling

Non-text content

Any other comments?

Uh oh!

netlify bot commented Sep 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for nebari-docs ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

krassowski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

viniciusdc commented Nov 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

viniciusdc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify bot commented Sep 24, 2024 •

edited

Loading

viniciusdc commented Nov 1, 2024 •

edited

Loading