diff --git a/docs/docs/explanations/advanced-custom-settings.md b/docs/docs/explanations/advanced-custom-settings.md index 453dd1ec..52394155 100644 --- a/docs/docs/explanations/advanced-custom-settings.md +++ b/docs/docs/explanations/advanced-custom-settings.md @@ -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: diff --git a/docs/docs/how-tos/jupyter-gallery.md b/docs/docs/how-tos/jupyter-gallery.md new file mode 100644 index 00000000..ef16c4a6 --- /dev/null +++ b/docs/docs/how-tos/jupyter-gallery.md @@ -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. + +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. + +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. + +**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) | +| 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) | +| 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 \ +and \ should be replaced with the actual encoding an 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," + 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," + git: https://gitlab....net/companyxyz/examples.git + account: examples + token: "" +``` + +## 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. diff --git a/docs/sidebars.js b/docs/sidebars.js index a6b6a0c5..4bc66c62 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -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", ], }, { diff --git a/docs/static/img/how-tos/jupyter-gallery-tile-download.png b/docs/static/img/how-tos/jupyter-gallery-tile-download.png new file mode 100644 index 00000000..177015a3 Binary files /dev/null and b/docs/static/img/how-tos/jupyter-gallery-tile-download.png differ diff --git a/docs/static/img/how-tos/jupyter-gallery-tile-update.png b/docs/static/img/how-tos/jupyter-gallery-tile-update.png new file mode 100644 index 00000000..a0b6d371 Binary files /dev/null and b/docs/static/img/how-tos/jupyter-gallery-tile-update.png differ diff --git a/docs/static/img/how-tos/jupyter-gallery-tiles.png b/docs/static/img/how-tos/jupyter-gallery-tiles.png new file mode 100644 index 00000000..f2506be9 Binary files /dev/null and b/docs/static/img/how-tos/jupyter-gallery-tiles.png differ