Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add doc on jupyterlab-gallery #528

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add doc on jupyterlab-gallery #528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2f54938
add doc on jupyter gallery
kcpevey Sep 24, 2024
c10f6b9
fix my inability to spell
kcpevey Sep 24, 2024
a495364
yarn linter
kcpevey Sep 24, 2024
eab3757
fix token description, add cross references jupyterlab overrides section
kcpevey Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/docs/explanations/advanced-custom-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ jupyterlab:

- `jupyterlab.preferred_dir` - Sets the default location in which JupyterLab should open the file browser in.

- `jupyterlab.gallery_settings` - Configures [`jupyterlab-gallery`](https://github.com/nebari-dev/jupyterlab-gallery) extension which enables user to clone (and later synchronise) pre-specified repositories.
- `jupyterlab.gallery_settings` - Configures [`jupyterlab-gallery`](https://github.com/nebari-dev/jupyterlab-gallery) extension which enables user to clone (and later synchronise) pre-specified repositories. See [How to set up a Git Repository via JupyterLab-Gallery](../how-tos/jupyter-gallery) for more detailed information.

```yaml
jupyterlab:
Expand Down
105 changes: 105 additions & 0 deletions docs/docs/how-tos/jupyter-gallery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
title: Share Git Repository via JupyterLab-Gallery
description: Share files or tutorials with your team
---

# How to set up a Git Repository via JupyterLab-Gallery

[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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


By default, if no JupyterLab-Gallery items are added to the config, users will not see this section
in the JupyterLab Launcher.

This feature was added to Nebari in the 2024.6.1 release.

## Configure JupyterLb-Gallery

In Nebari, the JupyterLab-Gallery configuration is set in the Nebari configuration, `nebari-config.yaml`.

The configuration is set under the `jupyterlab` section under the subsection `gallery_settings`.
Users may set a title for the Gallery section of the Launcher screen and a destination (i.e. folder)
for the location of the cloned repos.

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.
Comment on lines +25 to +27
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


The configuration is set at two different levels. Top level gallery settings define the title of
the Gallery section and the location in which the repositories are downloaded. The repository
level settings are defined for each repository. The descriptions of each section are described
below.
Comment on lines +31 to +32
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


**Top Level Gallery Settings**

| Section | Description |
| ----------- | -------------------------------------------------- |
| title | Title on the gallery tile |
| destination | Location on disk where the repo will be downloaded |

**Repository Level Settings**

| Section | Description |
| ----------- | ---------------------------------------------------------------------------- |
| title | Title on the gallery tile |
| git | URL of the git repository |
| homepage | (Optional) |
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what this is?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

| 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) |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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) |

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

| account | (Optional) |
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what this is?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

| token | Private Access Token to enable access to private repositories (Optional) |

### Sample configuration

Below is an example of the Gallery settings from the `nebari-config.yaml`. Note that \<encoding\>
and \<PAT\> should be replaced with the actual encoding an Private Access Token, respectively.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
and \<PAT\> should be replaced with the actual encoding an Private Access Token, respectively.
and \<PAT\> should be replaced with the actual encoding and Private Access Token, respectively.


```
jupyterlab:
gallery_settings:
title: Demos
destination: demos
exhibits:
- title: Data of an Unusual Size
git: https://github.com/nebari-dev/big-data-tutorial.git
description: Big data tutorial focusing on Dask usage in Nebari
icon: "data:image/png;base64,<encoding>"
homepage: https://github.com/nebari-dev/big-data-tutorial/
- title: From RAGs to riches
git: https://github.com/Quansight/ragna-presentations.git
homepage: https://github.com/Quansight/ragna-presentations/
- title: Private Examples
description: Internal company examples
icon: "data:image/png;base64,<encoding>"
git: https://gitlab....net/companyxyz/examples.git
account: examples
token: "<PAT>"
```

## Using JupyterLab-Gallery

Once the repositories are configured in the Nebari config and redeployed, all users will have
a section on their JupyterLab Launcher screen for the Gallery.

![JupyterLab Gallery tiles on JupyterLab Launcher screen](/img/how-tos/jupyter-gallery-tiles.png)

Each tile points to a different gallery entry in the configuration. The Gallery repositories
will not be downloaded until users trigger the download for each gallery item. To do so, users
will hover over the tile and click the download button.

![JupyterLab Gallery tile on hover for undownloaded repo](/img/how-tos/jupyter-gallery-tile-download.png)

The repository will download to the location specified in the config (in each user's private
space). After the download is complete, hover on the gallery tile present the users with two
new options - the folder icon allows them to jump to the location in the JupyterLab file browser,
and the download button allows them to fetch an updated copy of the repo (if available).

![JupyterLab Gallery tile on hover to update repo](/img/how-tos/jupyter-gallery-tile-update.png)

## Conclusion

For more information on the JupyterLab-Gallery project, visit the
[JupyterLab-Gallery codebase repo](https://github.com/nebari-dev/jupyterlab-gallery).

For more information about custom JupyterLab Overrides in the Nebari config, visit the [Custom Overrides Configurations](../explanations/custom-overrides-configuration#jupyterlab) documentation.
1 change: 1 addition & 0 deletions docs/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ module.exports = {
"how-tos/install-pip-packages",
"how-tos/fine-grained-permissions",
"how-tos/connect-via-ssh",
"how-tos/jupyter-gallery",
],
},
{
Expand Down
Binary file added docs/static/img/how-tos/jupyter-gallery-tile-download.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/how-tos/jupyter-gallery-tile-update.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/how-tos/jupyter-gallery-tiles.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading