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	`eab3757`
🔍 Latest deploy log	https://app.netlify.com/sites/nebari-docs/deploys/66f45d530067570008e40979
😎 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 site 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?

krassowski · 2024-09-25T18:31:50Z

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

+
+[JupyterLab-Gallery ](https://github.com/nebari-dev/jupyterlab-gallery) is a JupyterLab plugin
+that allows users to share a Git Repository. JupyterLab users are presented with a tile in
+the JupyterLab launch screen. Users can choose to download the Gallery.


Suggested change

the JupyterLab launch screen. Users can choose to download the Gallery.

the JupyterLab launch screen. Users can choose to download the Exhibit.

No strong opinions, I am just using the wording of "gallery composed of multiple exhibits" in jupyterlab-gallery and it seems to make more sense here.

Ah, I struggled with this wording - that is perfect!

krassowski · 2024-09-25T18:34:23Z

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

+level settings are defined for each repository. The descriptions of each section are described
+below.


Suggested change

level settings are defined for each repository. The descriptions of each section are described

below.

level settings are defined for each repository. The settings in each section are described

below.

Not a strong opinion here either

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.

krassowski · 2024-09-25T18:36:36Z

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

+| git         | URL of the git repository                                                    |
+| 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) |


Alternatively, this can be an URL.

Suggested change

| icon | base64 encoded image to use an icon to appear on the gallery tile (Optional) |

| icon | URL or base64 encoded image to use an icon to appear on the gallery tile (Optional) |

Though base64 encoding the image is probably best practice as it ensures that it will never break.

add doc on jupyter gallery

2f54938

kcpevey 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add doc on jupyterlab-gallery #528

Add doc on jupyterlab-gallery #528

kcpevey commented Sep 24, 2024

netlify bot commented Sep 24, 2024 •

edited

Loading

kcpevey Sep 24, 2024

krassowski Sep 25, 2024

krassowski Sep 25, 2024

kcpevey Sep 25, 2024

krassowski Sep 25, 2024

kcpevey Sep 24, 2024

krassowski Sep 25, 2024

krassowski Sep 25, 2024

kcpevey Sep 25, 2024

krassowski Sep 25, 2024

krassowski Sep 25, 2024

krassowski left a comment

krassowski Sep 25, 2024

kcpevey Sep 25, 2024

krassowski Sep 25, 2024

krassowski Sep 25, 2024

krassowski Sep 25, 2024

krassowski Sep 25, 2024

	the JupyterLab launch screen. Users can choose to download the Gallery.
	the JupyterLab launch screen. Users can choose to download the Exhibit.

		level settings are defined for each repository. The descriptions of each section are described
		below.

	\| icon \| base64 encoded image to use an icon to appear on the gallery tile (Optional) \|
	\| icon \| URL or base64 encoded image to use an icon to appear on the gallery tile (Optional) \|

Add doc on jupyterlab-gallery #528

Are you sure you want to change the base?

Add doc on jupyterlab-gallery #528

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?

netlify bot commented Sep 24, 2024 • edited Loading

✅ Deploy Preview for nebari-docs ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krassowski left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Sep 24, 2024 •

edited

Loading