Feature Request: Autogenerate template files with instructions for exercise development

[pwadsworth]

Issue:

The technical requirements and best practices information for contributing exercises and concepts is spread throughout multiple files in the site. This makes contributing more difficult than necessary and slows the growth of the track. This applies to other tracks as well, but is particularly important for tracks in development with smaller communities.

Recommendation:

A shell script (or CLI command?) could be included to generate all the template files and directories needed to create an exercise/concept. The following should be accomplished by the script:.

• The script receives as input the name for the exercise/concept and uses it to generate the file names, slugs, and appropriate entries in the configuration files.
• The script generates a todo.md describing the order and steps the contributor should follow, when/how to send for initial review, etc.
• The template files bring together all the instructions / requirements for that file and/or include dummy entries identified as requiring update.

Unfortunately my shell-fu does not allow me to take an initial stab at creating this script. So, I'll just leave it here for future consideration.

[ErikSchierboom]

A shell script (or CLI command?) could be included to generate all the template files and directories needed to create an exercise/concept. The following should be accomplished by the script:.

You point is totally valid and holds for all tracks. We probably want to build this into the configlet tool at some point.

[pwadsworth]

Here is a very plain implementation. What would you add/change?

#!/bin/sh

echo "Enter exercise name using only alphanumeric characters."

echo -n "In PascalCase for module name: "
read MODULE

echo -n "In kebab-case for directories: "
read STUB

BASEDIR="./exercises/concept/$STUB"
DOCS="$BASEDIR/.docs"
META="$BASEDIR/.meta"
EXEMPLAR="$META/exemplar"
EXEMPLAR_SRC="$EXEMPLAR/src"
SRC="$BASEDIR/src"
TEST="$BASEDIR/test"


mkdir -p -v $DOCS
mkdir -p -v $EXEMPLAR_SRC
mkdir -p -v $SRC
mkdir -p -v $TEST

#stack.yaml
cat <<EOF >$BASEDIR/stack.yaml
resolver: lts-18.14

EOF

#package.yaml
cat <<EOF >$BASEDIR/package.yaml
name: $STUB
version: 1.0.0.0

dependencies:
  - base

library:
  exposed-modules: $MODULE
  source-dirs: src
  ghc-options: -Wall
# dependencies:
#   - foo       # List here the packages you
#   - bar       # want to use in your solution.

tests:
  test:
    main: Tests.hs
    source-dirs: test
    dependencies:
      - $STUB
      - hspec

EOF

#.docs/hints.md
cat <<EOF >$DOCS/hints.md
# General

- General hint(s).

## 1. Task One

- Hint(s) for task one.

EOF


#.docs/instructions.md
cat <<EOF >$DOCS/instructions.md
# Instructions

<!--- 
  Provide general instruction for the exercise. 
  Start with a short scenario to motivate the problem.
-->

## 1. Task One

<!--- 
  Describe each task that needs to be accomplished separately.
  Often, tasks will align with functions that need to be implemented.
-->

EOF


#.docs/introduction.md
cat <<EOF >$DOCS/introduction.md
# Introduction

<!---
  Introduce all concepts necessary to complete de exercise.
  Provide similar code examples.  

  \`\`\`haskell
  41+1
  -> 42
  \`\`\`
-->

EOF

#.meta/config.json
cat <<EOF >$META/config.json
{
  "blurb": "TODO",
  "icon": "TODO",
  "authors": ["TODO"],
  "forked_from": ["TODO"],
  "files": {
    "solution": [
      "src/$MODULE.hs",
      "package.yaml"
    ],
    "test": [
      "test/Tests.hs"
    ],
    "exemplar": [
      ".meta/exemplar/src/$MODULE.hs"
    ]
  }
}

EOF


#.meta/design.md
cat <<EOF >$META/design.md
# Design

## Learning objectives

- Know how to ...
- Understand how to ...

## Out of scope

- Concept out of scope 1; concept out of scope 2.

## Concepts

- \`example-concept-stub\`

## Prequisites

- \`example-prerequisite-stub\`

EOF


#.meta/exemplar/src/Exemplar.hs
cat <<EOF >$EXEMPLAR_SRC/$STUB.hs
module $MODULE (exposedFunction) where

-- TODO: Create exemplar solution.
--       Use the most basic possible implementation of the concept. 
--       E.g. exposedFunction takes and Int and returns a String.

exposedFunction :: Int -> String
exposedFunction n = show n

EOF


#src/StarterFile.hs
cat <<EOF >$SRC/$MODULE.hs
module $MODULE (exposedFunction) where

-- TODO: Create stub solution from the exemplar.
--       E.g. exposedFunction takes and Int and returns a String.

exposedFunction :: Int -> String
exposedFunction n = error "Implement this function"

EOF


#test/Tests.hs
cat <<EOF >$TEST/Tests.hs
import Test.Hspec (it, shouldBe, hspec)
import $MODULE (exposedFunction)

--TODO: Create tests for all possible cases of exposed functions in 
--      the exemplar.

EOF

echo
echo "$STUB setup complete"

[ErikSchierboom]

You might want to also add an entry to the track's config.json file for the exercise.