Galleries are a way for SWAN users to publish examples in the form of Jupyter notebooks about a particular area or topic. They can be accessed from SWAN by clicking on the gallery icon (topmost bar, on the right) or directly at the SWAN gallery site.
If a SWAN user wishes to add a new gallery to the SWAN gallery site, they first need to create a GitHub repository that contains the notebooks to be shown in the gallery. The notebooks can be located in any subfolder of the repository, but the following requirements must be met:
-
There must be an
nbSnapshots
subfolder in any folder that contains notebooks (example). ThenbSnapshots
subfolder must contain one image for each of the notebooks with a snapshot of how the notebook looks like, which will be shown in the gallery to represent that notebook. A snapshot image file for a given notebook must have the same name of the notebook and.png
extension (example). -
If a notebook requires some input files to execute, such notebook and its input files must be located in subfolder whose name matches the name of the notebook without the
.ipynb
extension (example).
Once the repository is ready, its addition to the SWAN galleries can be requested by making a pull request to the SWAN galleries repository on Github. The PR must do the following actions:
-
Add your repository to the root folder of the SWAN galleries repository via a new git submodule.
-
Add a new
your_submodule_name.md
file for your repository to the docs folder (example). As you can see here for the previous example, such file is the README file shown for your repository in the SWAN galleries. The file must start with:
---
template: full_width_with_menu.html
---
After that, it must contain a list of the links to your notebooks. The path to each notebook must start from
the root directory and point to your_submodule_name/path/to/your_notebook.ipynb
. For example:
* [Simple ROOTbook (Python)](basic/notebooks/Simple_ROOTbook_py.ipynb)
If the notebook is located in a subfolder together with some input files, the link must be of the form
your_submodule_name/path/to/your_notebook/your_notebook.ipynb?clone_folder=True
. For example:
* [3D Visualisation](basic/notebooks/Geometry_Visualisation_cpp/Geometry_Visualisation_cpp.ipynb?clone_folder=True)
- Modify the mkdocs.yml file to add a new entry for
your gallery inside
nav
with the name of your submodule README file:
nav:
- your_submodule_name.md
- Optionally, an "Open in SWAN" banner can be added to the README file, so that the whole gallery is opened
in SWAN at once, not just individual notebooks. To do so, a line like the following one must be added to
your_submodule_name.md
:
[<img class="open_in_swan" data-path="your_submodule_name" alt="Open this Gallery in SWAN" src="https://swanserver.web.cern.ch/swanserver/images/badge_swan_white_150.png">][gallery_url]
where gallery_url
should be of the form https://cern.ch/swanserver/cgi-bin/go?projurl=https://github.com/myaccount/myrepo.git
.
See an example here.