Define a simple format for exercise README templates

[kytrinyx]

UPDATE: Nevermind. I realized that we can simply use go's text/template package for this.

Per the discussion about cross-track consistency and stand-alone exercises in #158 we need to define a simple README template that the tool can use to generate READMEs.

The tool will need to take the following structure into account:

.
├── problem-specifications
│   └── exercises
│       └── foo
│           ├── canonical-data.json
│           ├── description.md
│           └── metadata.yml
└── the-track
    ├── docs
    │   └── EXERCISE_README_INSERT.md
    └── exercises
        ├── bar
        │   ├── .meta
        │   │   ├── README_TEMPLATE.txt
        │   │   ├── description.md
        │   │   ├── example.ext
        │   │   └── metadata.yml
        │   ├── README.md
        │   ├── bar_test.ext
        │   └── fixtures
        │       ├── one.json
        │       └── two.json
        └── foo
            ├── .meta
            │   ├── README_TEMPLATE.txt
            │   └── example.ext
            ├── README.md
            └── foo_test.ext

Note:

• There are two "repositories" depicted here, problem-specifications, and the-track, which represents a fake Exercism language track.
• foo is an exercise that exists in the common pool of problem specifications.
• bar is a custom exercise that only this track has.
• bar has metadata files defined within .meta. This might actually not be necessary, but for now let's assume it is the case, since that's how we define custom exercises
• Eventually the exercise directory will contain exactly what the user will receive. There will only be one directory that gets ignored, and that is .meta. The .meta directory will contain ALL files that should not be sent to the user.
• For now, though, we need to take into account a HINTS.md file that might live in the exercise directory, to be included in the README template.
• The exercise directory might have nested subdirectories that will need to be delivered (e.g. fixtures in the bar exercises).

We need to decide on a name for the README_TEMPLATE.txt, including the extension. It will be markdown, with the addition of a file inclusion directive.

The template could be 100% markdown, in which case it simply gets copied to the exercise directory. OR, it could be 100% file inclusion directives, in which case it generates the README based on those directives. OR, it could be some combination of the above.

For the very first pass at this, we will put a default README_TEMPLATE.txt into every single exercise in every single track, and based on this the tool will generate the exact same README that the exercise currently has.

We need to take into account:

• The exercise name (based on the slug, but wordified: split on hyphen, title case)
• The exercise description which could be in one of two places:
  • problem-specifications/exercises/:slug/description.md
  • the-track/exercises/:slug/.meta/description.md
• The implementation hints from the HINTS.md file
• The track-level hints from docs/EXERCISE_README_INSERT.md

There might not be a HINTS file, there might not be an EXERCISE_README_INSERT.

Eventually, the HINTS file will go away, as this will just be text added directly to the template.

We need to decide on the format of the variable replacements and file inclusion directive. I don't much care what the format is, only that it's something that is unique and that we would never want to have as part of the final exercise README.

My suggestion is:

• {{VARIABLE_NAME}}
• {{include::file path/to/file}}

The path/to/file needs to take into account both the problem-specifications and the track itself. Maybe we can just assume that the path is relative to the track root so we'll have:

• ../problem-specifications/exercises/foo/description.md
• docs/EXERCISE_README_INSERT.md
• exercises/foo/HINTS.md
• exercises/foo/.meta/description.md

Other options that I can think of are relative to the exercises directory, or relative to the exercise directory itself (e.g. relative to the-track/exercises/foo).

Once we have this format specified, we can create the tool and the default template and generate all the READMEs based on what is currently generated.

[kytrinyx]

Nevermind. I realized that we can simply use go's text/template package for this.