This repo contains the Jupyter Book source files for the Hub Champion Training.
This lesson is aimed at Hub Champions in charge of 2i2c managed JupyterHubs in the cloud. Learn the fundamentals of administering your hub and providing user support to your research and education communities.
Training is delivered over two synchronous workshops, each one hour in length a week apart. The week in between is dedicated to self-guided study with asynchronous support provided by the instructors, which we estimate at least four hours of work.
[!WARNING] This lesson is a under active development.
[!NOTE] Versión en español
We recommend editing the contents of this repo using the 2i2c Community Showcase Hub.
[!NOTE] If you require collaborator access to contribute to this repo, please Get in Touch. Otherwise, you can fork this repository instead.
Access the 2i2c Community Showcase Hub at https://showcase.2i2c.cloud/. If you require authorisation to access this hub, please Get in Touch.
Select the Shared Small: 1-4 CPU, 8-32 GB server option and in the Image dropdown box select Handbook Authoring.
Once the JupyterLab interface has loaded, set up GitHub authentication with gh-scoped-creds
. This allows you to pull and push to GitHub repos securely. To enable this, open a terminal, run the command
gh-scoped-creds
and follow the prompts to enter your code at https://github.com/login/device
Git clone this project repo using the Terminal with the command
git clone https://github.com/czi-catalystproject/hub-champion-training.git
Follow the instructions in Localisation to Spanish for authoring and previewing content using Jupyter Book.
[!CAUTION] We do not recommend entering your GitHub credentials (GitHub password, personal access tokens or otherwise) on any kind of shared infrastructure (e.g. private and public cloud, HPC, any remote machine) as this information will be at risk. We highly advise using
gh-scoped-creds
for authentication on our hubs. Read this article for more information.
The following are instructions for localising the Jupyter Book to Spanish, adapted from the Sphinx documentation.
Open a Terminal and navigate to the hub-champion-training
folder
cd hub-champion-training/
If a config.py
file does not exist in this folder, or if you have made changes to _config.yml
, then automatically generate this from the _config.yml
with
jupyter-book config sphinx .
(See Jupyter Book docs)
Generate .pot
files with gettext
to extract all translatable strings from the doctree
jupyter-book build --builder custom --custom-builder gettext .
The generated .pot
files will be placed in the _build/gettext
directory. The .pot
files are empty template files and need to be updated if the source content changes. The msgid
line contains the source text. The empty msgstr
line will eventually contain the actual translation in the .po
file.
Create .po
files in the locale
folder in the es_LA
target language (ensure that the locale
folder matches the locale_dirs
setting in _config.yml
)
sphinx-intl update -p _build/gettext -d locale -l es_LA
The generated .po
files are the files that will contain the actual translations in the msgstr
lines that are created in the next step.
Translate the .po
files located inside the locale/es_LA/LC_MESSAGES
folder as required, e.g. with human translation services, machine translation or professional translation services with Crowdin.
Build the HTML files in English (the source language)
jupyter-book build .
Build the HTML files in Spanish (the target language)
jupyter-book config sphinx .
sphinx-build -b html -D language=es_LA . _build/html/es
Open a new Terminal and navigate to the HTML folder using the command
cd hub-champion-training/_build/html/
Run a simple Python webserver with the command
python -m http.server
Open a new browser tab and preview the Spanish version of the website by opening the following URL
https://<your-hub-url>/user/<your-username>/proxy/8000/es/index.html
[!TIP] If you run into the following error
sphinx.errors.SphinxError: This environment is incompatible with the selected builder, please choose another doctree directory.
try cleaning the build outputs first before building againjupyter-book clean . jupyter-book build .
On push to main:
.github/workflows/deploy_website.yml
.locale
directory are uploaded to the l10n
branch on Crowdin via the GitHub actions defined in .github/workflows/crowdin-action-upload.yml
.On cron schedule and manual trigger:
l10n
branch on GitHub and an automatic PR is opened.l10n
branch already exists on GitHub, then Crowdin translations will be force pushed to the l10n
branch on GitHub to the existing PR..github/workflows/crowdin-action-download.yml
.See CONTRIBUTING.md.
See LICENSE.md
We would like to acknowledge Chan Zuckerberg Initiative funding for the "A Collaborative Interactive Computing Service Model for Global Communities" project and our partner organisations:
If you would like to get in touch with us, then please open an issue or email support@2i2c.org.