Structure of an EVITA module

Important

An EVITA module is a combination of pedagogical material and working examples of code. These are presented to a learner in smaller logical units called episodes. The module extensively uses

  • Sphinx as the documentation engine,

  • MyST Parser to parse the content in Markdown and Jupyter notebooks,

  • sphinx-lesson to provide an extended set of markup known as directives, and

  • sphinx-evita to customize the appearance.

Overview

Module developers are expected to provide the following:

  • conf.py

  • index.md

  • An episodes directory containing

    • Jupyter notebooks preferably (Markdown and reStructuredText files are also acceptable; alternatively slides in ODP/PPTX and PDF pairs)

    • Images used in the notebooks

    • Longer code examples referenced in the notebooks as stand-alone file (Short code snippets can be described inline).

    • Demos and type-along sessions to introduce the topic

    • Discussions and exercises designed for formative assessment.

  • Questions and quizzes for summative assessment.

  • instructor-guide.md

  • reference-for-learners.md

  • CITATION.cff file

To sum up a new module is organized as shown below:

├── CITATION.cff
├── content
│   ├── conf.py
│   ├── episodes
│   │   ├── code
│   │   │   └── code-example.py
│   │   ├── images
│   │   │   └── inline-image-example.png
│   │   ├── ModuleName-1-EpisodeName.md
│   │   ├── ModuleName-2-EpisodeName.ipynb
│   │   ├── ModuleName-3-EpisodeName.md
│   │   └── quiz
│   │       ├── quiz_in_episodes.md
│   │       └── solution_for_quiz_in_episodes.md
│   ├── index.md
│   ├── instructor-guide.md
│   ├── reference-for-learners.md
│   └── _static
│       └── slides
│           ├── slides-3-EpisodeName.pdf
│           └── slides-3-EpisodeName.pptx
├── LICENSE
├── LICENSE.code
├── make.bat
├── Makefile
├── pylock.toml
├── pyproject.toml
└── README.md

The conf.py file

The conf.py file contains all the configuration for Sphinx. This includes details like title, authors, Sphinx extensions and their configuration. Some comments with FIXME: is provided where appropriate replacements should be made.

The index.md file

The index.md file is the landing page of the course. This should include:

  • Title of this module

  • General description (1–3 paragraphs)

  • Prerequisites

    • Reading materials or other preparation required before starting this module

  • Links to episodes in correct order

    • Must use the toctree syntax

    • At least three sections should be included:

        1. Software setup – instructions for configuring the programming environment

        1. Episodes – teaching content of the module divided into smaller units called episodes

        1. Reference – notes for instructors and additional resources

  • Learning outcomes (following Bloom’s Taxonomy guidelines)[3]

    • Target learners and practical skills they will gain

    • Links to relevant leaves in the skill tree

    • Optionally, mention related topics not covered in this module and link them to the skill tree

  • Credit (to be reformulated ASAP)

  • License (to be reformulated ASAP)

See also

The index.md file of this very own module template. You can view the source, by clicking on the eye icon on the top.

Episode on setting up programming environment

Provide a dedicated notebook (Markdown or reStructuredText also acceptable) with at least two sessions covering environment setup:

  • Local installation

    • Specify package versions (e.g., via requirements.txt or environment.yml)

    • Detailed setup instructions for Windows, macOS, and Linux users

    • Optionally provide a containerized setup

  • HPC cluster installation

    • Instructions valid for a specific supercomputer (preferably an EuroHPC cluster)

    • Specify package versions (as above)

    • Optionally provide a containerized setup

    • Example SLURM batch script for running exercises

  • Datasets

    • If a dataset is required and smaller than 100 MB, include it directly

    • If larger, provide instructions for downloading it from an external archive

See also

The setup episode.

Episodes for teaching

These episodes are the core content which introduces and goes deeper into the topic at hand. Each episode should include:

  • A general description

  • Objectives for learners

  • Instructor note (suggested time allocation, code demos, exercises, etc.)

  • At least one of the following between major sections:

    • Discussion

    • Code for demonstration

    • Exercise (with corresponding Solution)

  • Highlighted notifications such as Note, Caution, Attention, etc.

    • See the Jupyter Notebook titled Reference for module developers for more options

  • Images to illustrate key concepts (stored in an images directory)

  • Videos if needed to demonstrate continuous processes

    • Videos may be provided directly or linked from YouTube

  • Code examples stored in a code directory, with references in the notebook

  • Keypoints at the end of the episode, summarizing its content

  • See also with additional reading materials

See also

You can look at any of the episodes in this current example module. If you are starting something new, use this boilerplate episode.

Quiz

  • Provide summative assessment questions suitable for supervised or unsupervised evaluation

  • Formats may include:

    • Multiple-choice questions

    • Coding tasks

Note

The current page on quiz is for demonstration purposes only. The format may change.

Instructor guide

The instructor guide should include:

  • Recommended teaching hours and participant numbers

  • Mode of teaching and exercises

  • Hardware requirements (including HPC if applicable)

  • Learner personas

  • Additional teaching recommendations

See also

The instructor guide in the current example module.

Reference for Learners

  • Glossary of terms

  • External resources for further study

See also

The reference for learners in the current example module.

The CITATION.cff file

This citation file format file encodes metadata such as author information, affiliation and so on. You are also expected to tag appropriate skills related to HPC certification forum’s skill tree under the identifiers field. For example:

identifiers:
  - type: url
    value: >-
      https://www.hpc-certification.org/wiki/skill-tree/bda/2/6/b
    description: BDA2.6 Dask
  - type: url
    value: >-
      https://www.hpc-certification.org/wiki/skill-tree/sd/1/1/b
    description: SD1.1 Programming Languages
  - type: url
    value: >-
      https://www.hpc-certification.org/wiki/skill-tree/sd/1/3/b
    description: SD1.3 Efficient Algorithms and Data Structures
  # - type: doi
  #   value: 10.1234/zenodo.4321
  #   description: Module archive on Zenodo

See also

Citation file format generator.