IT, ist das was für mich?

Course notes and material for "IT, ist das was für mich?".

Website

The website serves as entry point for the participants and helps organize course notes as well as additional material relevant for the participants.

Technical Background

The website is markdown-based and rendered using a static site generator.

The following tools are at play:

• Sphinx
• Sphinx Book Theme
• Markedly Structured Text (MyST)

Sphinx is a mature, feature rich, versatile and extensible documentation generator.

While Sphinx is based on reStructuredText (reST), different markup languages are supported either natively or through plugins. The MyST parser allows for a more markdownish-writing experience.

The sphinx book theme is responsible for the appearance of the site.

Extensions are specified in the Sphinx configuration file conf.py.

The listed tools are used within the executable books project.

Setup

Use your favorite method to create a (virtual) Python environment based on the specifications in environment.yml or requirements.txt. Take a look at the CI workflow, i.e. .github/workflows/gh-pages.yml (or .gitlab-ci.yml).

Editing

Source files reside in the sources/ directory and are written using the Markdown flavor Markedly Structured Text (MyST) which is a superset of CommonMark Markdown.

To make changes, edit the already existing files or add a new document.

New documents need to be included through a toctree directive.

Take a look at both MyST and the theme to learn more about how to write content. To better understand the underlying principles, take a look at Sphinx.

Rendering/Building

To build locally, do

make html

To remove the build, do

make clean

Alternatively, sphinx-build can be invoked directly

$ sphinx-build -b html source/ public/  # to build
$ rm -r public  # to remove the build

Links are automatically checked in the CI pipeline. To run these checks locally, see the CI config.

CI Pages

A CI pipeline is configured and the build is automatically published.

Slides

Technical Background

Slides are markdown-based and rendered using Marp.

Note: To included slides on the website, at the PDF version as download.

Setup

VS Code Plugin

There is a VS Code plugin for local development and building.

Marp CLI

There is a CLI that can be installed through npm.

$ npm install -g @marp-team/marp-cli

Editing

Source files reside in the sources/course/days_*/slides.md and are written in Markdown.

Rendering/Building

To convert a markdown file into e.g. PDF, do

$ marp slides.md -o slides.pdf
$ npx @marp-team/marp-cli@latest slides.md -o slides.pdf  # included marp update

or use the VS Code plugin.

To simplify automation, use the SlidesMakefile.

$ make --makefile=SlidesMakefile all  # to compile all slides
$ make --makefile=SlidesMakefile clean  # to remove them
$ make --makefile=SlidesMakefile help  # to see other options

Spell Checking

CSpell can be used for spell checking.

There is an extension for VS Code as well a dictionary for German.

Building Everything

$ ./run.sh to render both slides and website in one go.

Note that run.sh builds the development or work in progress (wip) version of the website whereas the CI service only builds publication-ready-content. See how the exclude_patterns is specified in conf.py. The toggle is implemented using tags passed to the build commands.

New Intake Actions

In this sections we briefly describe the required actions when a new intake starts.

1. Rename old repository and old team (to free names)
2. Create new repository and new team
3. Copy-paste old website into new repository, thereby
   • Discarding the Git-history
   • Deleting participant-related content We do that to avoid storing participant-related information longer than necessary.
4. Migrate eventual issues to new project
5. Delete old repository and old team (if not done already)

To activate GitHub Pages: On GitHub / Settings / GitHub Pages select

• Source: Deploy from branch
• Branch: gh-pages / (root) Save