Alemira Coding Labs exercise source format

Sources for examples of known coding exercise formats

1. The Odin Project: sumAll
2. freeCodeCamp: remove items from an array with pop() and shift()
3. Exercism: language-agnostic problem specifications, language-specific practice exercises (C#)

What kind of lightweight markup we need for Coding Labs

Current CL source format requirements:

1. It should be as versatile as possible in order to support authoring exercises in any programming language.
2. It should be clear to instructors who author exercises. For programming instructors, we can assume that they're proficient enough in what they teach, and they are able to write code for exercises (probably aided by some sort of code generation). If necessary, we'll later be able to put a UI on top of this for less tech-savvy instructors.
3. It should be VCS compatible: if necessary, an instructor should be able to check out exercises to their local machine and proceed with editing in their favorite editor. In this respect, having a simple Git hosting is a big plus, and we'll probably add GitHub/GitLab integration later.
4. It should support both novice-friendly exercises that contain multiple instructions and more complex projects for more advanced students.
5. Going forward, it should support integration into larger courseware written in a lightweight markup language such as Markdown, RST, or LiaScript.

Initial Markdown-based format proposal

The current proposed exercise format (considerably inspired by Exercism) uses Markdown and requires exactly one non-standard Markdown feature: custom containers.

Custom containers enable designated markup for hints (:::hint) and tests (:::tests) in exercise definitions. Custom containers are available in many Markdown parsers, including Markdig, markdown-it, and markdown-it-py. Based on this this babelmark test, markdig in advanced mode correctly transforms custom containers out of the box. Other parsers (such as markdown-it) can potentially do this, too, but require additional configuration.

Markdown features that we may possibly need to enable non-practical Markdown-based content

It's not exactly clear what we'll need for authoring non-exercise content, but based on GitBook-based and Sphinx-based content researched, the following Markdown features would be very nice to have in the future:

• include. Allows to include one file into another. Useful to include blocks of content that are reused in multiple places. Available in GitBook. Sphinx provides both include and literalinclude (which only differ in error handling):

    .. literalinclude:: php_time_test.php
        :caption: php_time_test.php
        :linenos:
        :language: html
  

• toctree. Allows rendering a table of contents based on parts of a file tree. Used in Sphinx (docs). Example:

  .. toctree::
     :maxdepth: 1
  
     semester_1/index
     semester_2/index
     about
  

• csv-table. Allows to create tables based on external CSV content, which allows editing tabular data in spreadsheets. Used in Docutils/Sphinx (docs). Example:

  .. csv-table::
     :file: class_schedule.csv
     :widths: 15, 55, 30
     :header-rows: 1
  

• [#n]. Enables footnotes (docs). Example:

  .. [#f1] Wikipedia contributors. (2021, January 21).
     "`Web application security <https://en.wikipedia.org/wiki/Web_application_security>`_".
     In Wikipedia, The Free Encyclopedia. Retrieved 17:32, January 31, 2021,
     from https://en.wikipedia.org/w/index.php?title=Web_application_security&oldid=1001721387
  

Todo items

• Split exercise into 2 instructions
• Try the same approach with Python
• Try the same approach with JavaScript
• Address issues: naming conventions to define different kinds of files (examples, initial, tests) will be hard to maintain because of language-specific conventions (i.e. title case for files in C# and lowercase in Python and JavaScript; special meaning for dot in file names in Python, etc.)
• Define requirements for Markdown-based format
• Try the updated approach with Kotlin
• Try the updated approach with Java
• Try the updated approach with multi-file exercises in C# (ASP.NET Core?)
• Try the updated approach with multi-file exercises in Java (take a template from Codeboard)
• Should each C# exercise be a separate project?