The web site can is built using the mkdocs tool that is also used for the
main LUMI documentation.
However, the version of the software that is used to build this web site may be
different, and some additional packages may be employed. See the
requirements.txt file in the repository.
All development is done in a fork of the repository. GitHub is set up with
upstream as the remote name for the
main repository on the lumi-supercomputer GitHub
while originis used as the remote name for the fork in which all work is being done.
IF the repositories are set up in this way, then the following Makefile targets can be used to build the web site:
serveorpreview: Preview the web site on your computer. (Point the browser to - usually - localhost:8000)build: Build locally, not very useful.deploy-origin: Deploy the web site to the remoteorigin, i.e., the fork, which is ideal for testing without disrupting the production site.deploy-upstream: Deploy the web site to the remoteupstream, i.e., the production site on lumi-supercomputer.github.io
Alternatively, it is also possible to rebuild the website using a GitHub action. The options are:
-
When pushing to the main branch, the rebuild process will run automatically. So be careful not to push unfinished work as this would bring the web site in an inconsistent state.
-
It is aso possible to run the action manually:
-
Go to the repository in the web interface of GitHub (well, you might be there if you read this)
-
Click the "Actions" menu at the top of the screen.
-
In the left column, chose "Deploy on push to main or manually"
-
Now select the "Run workflow" dropdown box at the right
-
And use the drop-down box that appears now to select the branch.
-
And finally click on "Run workflow"
-
The preferred workflow is to do all work via branches. During a course, when frequent updating of the web
site is needed, it is better not to work on the main branch but on one branch for the duration of the course
and process from that branch either by running mkdocs on your laptop or by triggering the deploy action
manually in the branch that you are working on. In that way, if an annoying mess-up is made during the course,
it is always easy to restore the training materials web site to the hopefully consistent state from before the
course.
-
Each regular course has its own subdirectory with materials in the
docssubdirectory. As such it becomes rather easy to archive that material when no longer relevant.Hackathon materials are also considered as a course.
Each course also has its own subdirectory in the LUMI-training-lumio
coursessubdirectory. The capitalisation of the name in there may be different as it has to be a valid bucket name and it turns out that it the character range that can be used for the name of a bucket on LUMI-O is rather limited, e.g., no capitals. -
The user coffee break material is considered as a special course, so get a subdirectory (
User-Coffee-Breaks) with further organisation in that subdirectory. There is currently a single bucket on LUMI-O for all material of the coffee breaks (user-coffee-breaks). -
The User Update docs and sessions made after some system updates are also together considered as a special course with currently a single bucket on LUMI-O for all material. Again we do make a further structure in the
User-Updatessubdirectory in this repository and can do the same in theuser-updatesbucket.
Other subdirectories:
docs/assetscurrently only contains the favicon.docs/stylesheetscontains the stylesheet used to define extra admonitions.- The contents of
site_customisationsis largely based on that for the LUMI docs
Large files (e.g., tar files, images, PDFs) are not stored on GitHub but on
LUMI-O. The data is pushed to LUMI-O from a laptop on which the data is
prepared using rclone. Some data is public, some data is private.
Scripts to facilitate data management per course can be found in the
LUMI-training-lumio repository
but the way of working may need some further information that will be provided
in that repository.