From 842b3d6416aa6e90837f0eecf46af41e7d631ab7 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Wed, 23 Dec 2020 10:47:04 +0100 Subject: [PATCH 1/8] [Anatomy] Add configlet documentation --- anatomy/configlet.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 anatomy/configlet.md diff --git a/anatomy/configlet.md b/anatomy/configlet.md new file mode 100644 index 00000000..6a656e9d --- /dev/null +++ b/anatomy/configlet.md @@ -0,0 +1,19 @@ +_work in progress_ + +# Configlet + +[configlet](https://github.com/exercism/configlet) is a tool to help track maintainers with the maintenance of their track. The current version of configlet works with v2 tracks, but a version that works with v3 tracks is [under development](https://github.com/exercism/canonical-data-syncer). This document will only describe the v3 version of configlet. + +## Linting + +The primary function of configlet is to do _linting_: checking if a track is properly configured. If this is not the case, the track won't work properly (or at all). The full list of rules that are checked by the linter can be found [here](https://github.com/exercism/canonical-data-syncer/blob/master/linting.md). + +## Usage + +configlet is distributed as a standalone binary. To integrate configlet in your track, you should add one (or both) of the fetch scripts [defined here](https://github.com/exercism/configlet/tree/master/scripts), which can then be used to download the binary for your operating system/architecture. + +## CI + +All tracks should integrate the configlet lint functionality in their CI setup. The easiest way to do this is by using the [configlet CI GitHub action](https://github.com/exercism/github-actions/tree/master/configlet-ci). + +TODO: describe other configlet features From f4b5b54f301f01d55f1346de07ae0820d373b306 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Wed, 23 Dec 2020 13:29:52 +0100 Subject: [PATCH 2/8] Fix intro --- anatomy/{ => tracks}/configlet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename anatomy/{ => tracks}/configlet.md (77%) diff --git a/anatomy/configlet.md b/anatomy/tracks/configlet.md similarity index 77% rename from anatomy/configlet.md rename to anatomy/tracks/configlet.md index 6a656e9d..8b35bd2a 100644 --- a/anatomy/configlet.md +++ b/anatomy/tracks/configlet.md @@ -2,7 +2,7 @@ _work in progress_ # Configlet -[configlet](https://github.com/exercism/configlet) is a tool to help track maintainers with the maintenance of their track. The current version of configlet works with v2 tracks, but a version that works with v3 tracks is [under development](https://github.com/exercism/canonical-data-syncer). This document will only describe the v3 version of configlet. +[configlet](https://github.com/exercism/configlet) is a tool to help track maintainers with the maintenance of their track. ## Linting From 27181021392e26b3439204635f7ce544e0c42bc2 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Wed, 23 Dec 2020 13:30:38 +0100 Subject: [PATCH 3/8] Apply review feedback --- anatomy/tracks/configlet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anatomy/tracks/configlet.md b/anatomy/tracks/configlet.md index 8b35bd2a..ed99bc5c 100644 --- a/anatomy/tracks/configlet.md +++ b/anatomy/tracks/configlet.md @@ -6,7 +6,7 @@ _work in progress_ ## Linting -The primary function of configlet is to do _linting_: checking if a track is properly configured. If this is not the case, the track won't work properly (or at all). The full list of rules that are checked by the linter can be found [here](https://github.com/exercism/canonical-data-syncer/blob/master/linting.md). +The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism. The full list of rules that are checked by the linter can be found [here](https://github.com/exercism/canonical-data-syncer/blob/master/linting.md). ## Usage From 082c82e09ff5ddffa36a0da0d79b48f05cb9ebac Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Wed, 23 Dec 2020 13:36:46 +0100 Subject: [PATCH 4/8] Add linting rules --- anatomy/tracks/configlet-linting.md | 209 ++++++++++++++++++++++++++++ anatomy/tracks/configlet.md | 2 +- 2 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 anatomy/tracks/configlet-linting.md diff --git a/anatomy/tracks/configlet-linting.md b/anatomy/tracks/configlet-linting.md new file mode 100644 index 00000000..d1e679cc --- /dev/null +++ b/anatomy/tracks/configlet-linting.md @@ -0,0 +1,209 @@ +# Configlet linting + +The primary use of [configlet](./configlet.md) is linting. These are the linting rules being checked. + +## Rule: required files are present + +The linter should check if all the required files are present. The non-exercise specific files that must be present are: + +- `config.json` +- `config/maintainers.json` + +The Concept Exercise specific files that must be present are: + +- `exercises/concept//.docs/hints.md` +- `exercises/concept//.docs/instructions.md` +- `exercises/concept//.docs/introduction.md` +- `exercises/concept//.meta/config.json` + +There will be a similar list for Practice Exercises, but we've not yet defined the spec for that. + +Each concept listed in the `config.json` should have the following files: + +- `concepts//about.md` +- `concepts//introduction.md` (pending agreement on https://github.com/exercism/v3/issues/2767) +- `concepts//links.json` + +## Rule: config.json file is valid + +The `config.json` file should have the following checks: + +- The file must be valid JSON +- The `"language"` key is required +- The `"language"` value must be a non-empty string +- The `"slug"` key is required +- The `"slug"` value must be a non-empty, lowercased string using kebab-case +- The `"active"` key is required +- The `"active"` value must be a boolean +- The `"blurb"` key is required +- The `"blurb"` value must be a non-empty string +- The `"version"` key is required +- The `"version"` value must be the integer `3` +- The `"online_editor.indent_style"` key is required +- The `"online_editor.indent_style"` value must be the string `space` or `tab` +- The `"online_editor.indent_size"` key is required +- The `"online_editor.indent_size"` value must be a positive integer (>= 0) +- The `"exercises"` key is required +- The `"exercises.concept"` key is required +- The `"exercises.concept"` value must be an array +- The `"exercises.concept[].slug"` key is required +- The `"exercises.concept[].slug"` value must be a non-empty, lowercased string using kebab-case +- The `"exercises.concept[].slug"` value must be unique in `"exercises.concept[].slug"` and may not exist in `"exercises.practice[].slug"` +- The `"exercise.concept[].name"` key is required +- The `"exercise.concept[].name"` value must be a non-empty string +- The `"exercise.concept[].uuid"` key is required +- The `"exercise.concept[].uuid"` value must be a unique UUID +- The `"exercise.concept[].deprecated"` key is optional +- The `"exercise.concept[].deprecated"` value must be a boolean value +- The `"exercise.concept[].deprecated"` value must generate a warning if set to `false` +- The `"exercise.concept[].concepts"` key is required +- The `"exercise.concept[].concepts"` value must be a non-empty array of strings +- The `"exercise.concept[].concepts"` values must be non-empty, lowercased strings using kebab-case +- The `"exercise.concept[].concepts"` values must not have duplicates +- The `"exercise.concept[].concepts"` values must not be in any other concept exercise's `"concepts"` property +- The `"exercise.concept[].concepts"` values must match the `"concepts.slug"` property of one of the concepts +- The `"exercise.concept[].prerequisites"` key is required +- The `"exercise.concept[].prerequisites"` value must be a non-empty array of strings for all but one exercise, which can have an empty array as its value +- The `"exercise.concept[].prerequisites"` values must be non-empty, lowercased strings using kebab-case +- The `"exercise.concept[].prerequisites"` values must not have duplicates +- The `"exercise.concept[].prerequisites"` values must match any other concept exercise's `"concepts"` property values +- The `"exercise.concept[].prerequisites"` values must not match any of the values in the exercise's `"exercise.concept[].concepts"` property +- The `"exercise.concept[].prerequisites"` values must match the `"concepts.slug"` property of one of the concepts +- There must not be any cycles between `"exercise.concept[].concepts"` and `"exercise.concept[].prerequisites"` +- The `"exercises.practice"` key is required +- The `"exercises.practice"` value must be an array +- The `"exercise.practice[].slug"` key is required +- The `"exercise.practice[].slug"` value must be a non-empty, lowercased string using kebab-case +- The `"exercise.practice[].slug"` value must be unique in `"exercises.practice[].slug"` and may not exist in `"exercises.concept[].slug"` +- The `"exercise.practice[].name"` key is required +- The `"exercise.practice[].name"` value must be a non-empty string +- The `"exercise.practice[].uuid"` key is required +- The `"exercise.practice[].uuid"` value must be a unique UUID +- The `"exercise.practice[].deprecated"` key is optional +- The `"exercise.practice[].deprecated"` value must be a boolean value +- The `"exercise.practice[].deprecated"` value must generate a warning if set to `false` +- The `"exercise.practice[].difficulty"` key is required +- The `"exercise.practice[].difficulty"` value must be an integer >= 0 and <= 10 +- The `"exercise.practice[].prerequisites"` key is required +- The `"exercise.practice[].prerequisites"` value must be a non-empty array of strings +- The `"exercise.practice[].prerequisites"` values must be non-empty, lowercased strings using kebab-case +- The `"exercise.practice[].prerequisites"` values must not have duplicates +- The `"exercise.practice[].prerequisites"` values must match any concept exercise's `"exercise.concept[].concepts"` values +- The `"exercise.practice[].prerequisites"` values must match the `"concepts.slug"` property of one of the concepts +- The `"exercises.foregone"` key is optional +- The `"exercises.foregone"` value must be a non-empty array of strings +- The `"exercises.foregone"` values must be non-empty, lowercased strings using kebab-case +- The `"exercises.foregone"` values must not match any of the concept or practice exercise slugs +- The `"concepts"` key is required +- The `"concepts"` value must be an array +- The `"concepts"` value must have a entry with a matching `"slug"` property for each concept listed in a concept exercise's `"concepts"` property +- The `"concepts[].uuid"` key is required +- The `"concepts[].uuid"` value must be a unique UUID +- The `"concepts[].slug"` key is required +- The `"concepts[].slug"` value must be a non-empty, lowercased string using kebab-case +- The `"concepts[].name"` key is required +- The `"concepts[].name"` value must be a non-empty, titleized string +- The `"concepts[].blurb"` key is required +- The `"concepts[].blurb"` value must be a non-empty string +- Each `"concepts"` value must have a `concept//about.md` file. Linting rules for this file are specified below. +- Each `"concepts"` value must have a `concept//introduction.md` file (pending agreement on https://github.com/exercism/v3/issues/2767). Linting rules for this file are specified below. +- Each `"concepts"` value must have a `concept//links.json` file. Linting rules for this file are specified below. +- The `"key_features"` key is optional +- The `"key_features"` value must be an array with length <= 6 +- The `"key_features[].icon"` key is required +- The `"key_features[].icon"` value must be a string that matches one of the pre-defined icon values (TODO: add link to list of icons) +- The `"key_features[].title"` key is required +- The `"key_features[].title"` value must be a non-empty string with length <= 25 +- The `"key_features[].content"` key is required +- The `"key_features[].content"` value must be a non-empty string with length <= 100 +- The `"tags"` key is optional +- The `"tags"` value must be a non-empty array of strings +- The `"tags"` values must use one of the pre-defined tag values (TODO: add link to list of tags) + +## Rule: config/maintainers.json file is valid + +- The file must be valid JSON +- The JSON root must be an object +- The `"maintainers"` key is required +- The `"maintainers"` value must be an array +- The `"maintainers"` array elements must use the correct format (TODO: specify) +- There must not be duplicate maintainers + +## Rule: exercises/concept/<slug>/.meta/config.json is valid + +- The file must be valid JSON +- The JSON root must be an object +- The `"authors"` key is required +- The `"authors"` value must be an non-empty array +- The `"authors[].github_username"` key is required +- The `"authors[].github_username"` key must be a non-empty string +- The `"authors[].github_username"` value is treated case-insensitively +- The `"authors[].exercism_username"` key is required +- The `"authors[].exercism_username"` key must be a non-empty string +- The `"authors[].github_username"` value is treated case-insensitively +- The `"contributors"` key is optional +- The `"contributors"` value must be an array +- The `"contributors[].github_username"` key is required +- The `"contributors[].github_username"` key must be a non-empty string +- The `"contributors[].github_username"` value is treated case-insensitively +- The `"contributors[].exercism_username"` key is required +- The `"contributors[].exercism_username"` key must be a non-empty string +- The `"contributors[].exercism_username"` value is treated case-insensitively +- Users can only be listed in either the `"authors"` or `"contributors"` array (no overlap) +- The `"editor.solution_files"` key is required +- The `"editor.solution_files"` value must be a non-empty array +- The `"editor.test_files"` key is required +- The `"editor.test_files"` value must be a non-empty array +- The files listed in the `"editor.solution_files"` must exist +- The files listed in the `"editor.test_files"` must exist +- Files can only be listed in either the `"editor.solution_files"` or `"editor.test_files"` array (no overlap) +- The `"forked_from"` key is optional +- The `"forked_from"` value must be a non-empty array +- The `"forked_from"` values must be strings formatted as `/` (e.g. `fsharp/bird-watcher`) +- The `"forked_from"` values must refer to actually implemented exercises +- The `"forked_from"` values must be unique +- The `"language_versions"` key is optional +- The `"language_versions"` value must be a string + +## Rule: exercises/concept/<slug>/.docs/hints.md is valid + +- If there are sub headings, they must start at level two +- All headings must be level two headings +- All headings must be either `## General` or `## X. ` where `X` matches the task number heading in the `instructions.md` +- All hints must be specified as Markdown list items + +## Rule: exercises/concept/<slug>/.docs/instructions.md is valid + +- If there are sub headings, they must start at level two +- All tasks must start with a level two heading that starts with a number followed by a dot: `## 1. Do X` + +## Rule: exercises/concept/<slug>/.docs/introduction.md is valid + +- If there are sub headings, they must start at level two + +## Rule: exercises/shared/.docs/cli.md is valid + +- If there are sub headings, they must start at level two + +## Rule: exercises/shared/.docs/debug.md is valid + +- If there are sub headings, they must start at level two + +## Rule: concepts/<slug>/about.md is valid + +- If there are sub headings, they must start at level two + +## Rule: concepts/<slug>/introduction.md is valid (pending agreement on https://github.com/exercism/v3/issues/2767) + +- If there are sub headings, they must start at level two + +## Rule: concept/<slug>/links.json is valid + +- The file must be valid JSON +- The JSON root must be an array +- The `"[].url"` property is required +- The `"[].url"` value must be an URL +- The `"[].description"` property is required +- The `"[].description"` value must be a non-empty string +- The `"[].icon_url"` property is optional +- The `"[].icon_url"` value must be an URL diff --git a/anatomy/tracks/configlet.md b/anatomy/tracks/configlet.md index ed99bc5c..f81bb13d 100644 --- a/anatomy/tracks/configlet.md +++ b/anatomy/tracks/configlet.md @@ -6,7 +6,7 @@ _work in progress_ ## Linting -The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism. The full list of rules that are checked by the linter can be found [here](https://github.com/exercism/canonical-data-syncer/blob/master/linting.md). +The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism. The full list of rules that are checked by the linter can be found [here](./configlet-linting.md). ## Usage From 42c07c7acf51909032a19adb2aa27b2393ef6040 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Wed, 23 Dec 2020 13:46:41 +0100 Subject: [PATCH 5/8] Rename directory --- anatomy/tracks/{configlet.md => configlet/README.md} | 2 +- anatomy/tracks/{configlet-linting.md => configlet/linting.md} | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename anatomy/tracks/{configlet.md => configlet/README.md} (93%) rename anatomy/tracks/{configlet-linting.md => configlet/linting.md} (99%) diff --git a/anatomy/tracks/configlet.md b/anatomy/tracks/configlet/README.md similarity index 93% rename from anatomy/tracks/configlet.md rename to anatomy/tracks/configlet/README.md index f81bb13d..3f10de7b 100644 --- a/anatomy/tracks/configlet.md +++ b/anatomy/tracks/configlet/README.md @@ -6,7 +6,7 @@ _work in progress_ ## Linting -The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism. The full list of rules that are checked by the linter can be found [here](./configlet-linting.md). +The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism. The full list of rules that are checked by the linter can be found [here](./linting.md). ## Usage diff --git a/anatomy/tracks/configlet-linting.md b/anatomy/tracks/configlet/linting.md similarity index 99% rename from anatomy/tracks/configlet-linting.md rename to anatomy/tracks/configlet/linting.md index d1e679cc..6cd17a3f 100644 --- a/anatomy/tracks/configlet-linting.md +++ b/anatomy/tracks/configlet/linting.md @@ -1,6 +1,6 @@ # Configlet linting -The primary use of [configlet](./configlet.md) is linting. These are the linting rules being checked. +The primary use of [configlet](./README.md) is linting. These are the linting rules being checked. ## Rule: required files are present From 0b69d30db7a60b7e830f54c6370b50b06450369e Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Thu, 24 Dec 2020 12:16:49 +0100 Subject: [PATCH 6/8] Update UUID linting rules --- anatomy/tracks/configlet/linting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/anatomy/tracks/configlet/linting.md b/anatomy/tracks/configlet/linting.md index 6cd17a3f..0435d561 100644 --- a/anatomy/tracks/configlet/linting.md +++ b/anatomy/tracks/configlet/linting.md @@ -52,7 +52,7 @@ The `config.json` file should have the following checks: - The `"exercise.concept[].name"` key is required - The `"exercise.concept[].name"` value must be a non-empty string - The `"exercise.concept[].uuid"` key is required -- The `"exercise.concept[].uuid"` value must be a unique UUID +- The `"exercise.concept[].uuid"` value must be a unique, lowercased v4 UUID string - The `"exercise.concept[].deprecated"` key is optional - The `"exercise.concept[].deprecated"` value must be a boolean value - The `"exercise.concept[].deprecated"` value must generate a warning if set to `false` @@ -78,7 +78,7 @@ The `config.json` file should have the following checks: - The `"exercise.practice[].name"` key is required - The `"exercise.practice[].name"` value must be a non-empty string - The `"exercise.practice[].uuid"` key is required -- The `"exercise.practice[].uuid"` value must be a unique UUID +- The `"exercise.practice[].uuid"` value must be a unique, lowercased v4 UUID string - The `"exercise.practice[].deprecated"` key is optional - The `"exercise.practice[].deprecated"` value must be a boolean value - The `"exercise.practice[].deprecated"` value must generate a warning if set to `false` @@ -98,7 +98,7 @@ The `config.json` file should have the following checks: - The `"concepts"` value must be an array - The `"concepts"` value must have a entry with a matching `"slug"` property for each concept listed in a concept exercise's `"concepts"` property - The `"concepts[].uuid"` key is required -- The `"concepts[].uuid"` value must be a unique UUID +- The `"concepts[].uuid"` value must be a unique, lowercased v4 UUID string - The `"concepts[].slug"` key is required - The `"concepts[].slug"` value must be a non-empty, lowercased string using kebab-case - The `"concepts[].name"` key is required From 47499c8f451fd0f0fcca6bf56f1d7705225edbe8 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Thu, 7 Jan 2021 09:33:43 +0100 Subject: [PATCH 7/8] Remove pending status --- anatomy/tracks/configlet/linting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/anatomy/tracks/configlet/linting.md b/anatomy/tracks/configlet/linting.md index 0435d561..0891c8c7 100644 --- a/anatomy/tracks/configlet/linting.md +++ b/anatomy/tracks/configlet/linting.md @@ -21,7 +21,7 @@ There will be a similar list for Practice Exercises, but we've not yet defined t Each concept listed in the `config.json` should have the following files: - `concepts//about.md` -- `concepts//introduction.md` (pending agreement on https://github.com/exercism/v3/issues/2767) +- `concepts//introduction.md` - `concepts//links.json` ## Rule: config.json file is valid @@ -106,7 +106,7 @@ The `config.json` file should have the following checks: - The `"concepts[].blurb"` key is required - The `"concepts[].blurb"` value must be a non-empty string - Each `"concepts"` value must have a `concept//about.md` file. Linting rules for this file are specified below. -- Each `"concepts"` value must have a `concept//introduction.md` file (pending agreement on https://github.com/exercism/v3/issues/2767). Linting rules for this file are specified below. +- Each `"concepts"` value must have a `concept//introduction.md` file. Linting rules for this file are specified below. - Each `"concepts"` value must have a `concept//links.json` file. Linting rules for this file are specified below. - The `"key_features"` key is optional - The `"key_features"` value must be an array with length <= 6 @@ -193,7 +193,7 @@ The `config.json` file should have the following checks: - If there are sub headings, they must start at level two -## Rule: concepts/<slug>/introduction.md is valid (pending agreement on https://github.com/exercism/v3/issues/2767) +## Rule: concepts/<slug>/introduction.md is valid - If there are sub headings, they must start at level two From 20d99db00f5c96f00a2c85ccf116316e15ede8bf Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Thu, 7 Jan 2021 10:01:40 +0100 Subject: [PATCH 8/8] Add generating option --- anatomy/tracks/configlet/README.md | 9 +++++ .../tracks/configlet/generating-documents.md | 25 ++++++++++++ anatomy/tracks/configlet/linting.md | 38 ++++++++++++------- 3 files changed, 59 insertions(+), 13 deletions(-) create mode 100644 anatomy/tracks/configlet/generating-documents.md diff --git a/anatomy/tracks/configlet/README.md b/anatomy/tracks/configlet/README.md index 3f10de7b..3364c1b6 100644 --- a/anatomy/tracks/configlet/README.md +++ b/anatomy/tracks/configlet/README.md @@ -8,6 +8,15 @@ _work in progress_ The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism. The full list of rules that are checked by the linter can be found [here](./linting.md). +## Generating documents + +The secondary function of configlet is to generate documents. There are two types of documents that configlet can generate: + +1. A Concept Exercise's [`introduction.md` file](./generating-documents.md#documentconceptexercisesintroductionmdfile). +1. A Practice Exercise's [`README.md` file](./generating-documents.md#documentpracticeexercisesreadmemdfile). + +How these documents are generated can be found [here](./generating-documents.md). + ## Usage configlet is distributed as a standalone binary. To integrate configlet in your track, you should add one (or both) of the fetch scripts [defined here](https://github.com/exercism/configlet/tree/master/scripts), which can then be used to download the binary for your operating system/architecture. diff --git a/anatomy/tracks/configlet/generating-documents.md b/anatomy/tracks/configlet/generating-documents.md new file mode 100644 index 00000000..2e95bb64 --- /dev/null +++ b/anatomy/tracks/configlet/generating-documents.md @@ -0,0 +1,25 @@ +# Configlet generating documents + +The secondary use of [configlet](./README.md) is generating documents. + +## Usage + +TODO: describe the command-line interface (command + options). + +## Documents + +These are the documents that configlet can generate. + +### Document: Concept Exercise's introduction.md file + +Each [Concept Exercise](../concept-exercises.md) has an [`introduction.md` file](../concept-exercises.md#docsintroductionmd). Each exercise can have an optional [`introduction.md.tpl` file](../concept-exercises.md#docsintroductionmdtploptional). + +The template file should be treated like a regular Markdown file but with one addition: the ability to specify placeholders. The following placeholders are supported: + +- `%{concept:}`: refers to the concept's [`introduction.md` document](../concepts.md#fileintroductionmd) + +When configlet detects that an exercise has an `introduction.md.tpl` file, it will generate a `introduction.md` file from it. The generated introduction will have the same contents as the template, expect for the placeholders, which will be replaced with the contents of the documents they refer to. + +### Document: Practice Exercise's README.md file + +TODO: document how generating the README.md file works diff --git a/anatomy/tracks/configlet/linting.md b/anatomy/tracks/configlet/linting.md index 0891c8c7..243721d0 100644 --- a/anatomy/tracks/configlet/linting.md +++ b/anatomy/tracks/configlet/linting.md @@ -1,8 +1,16 @@ # Configlet linting -The primary use of [configlet](./README.md) is linting. These are the linting rules being checked. +The primary use of [configlet](./README.md) is linting. -## Rule: required files are present +## Usage + +TODO: describe the command-line interface (command + options). + +## Rules + +These are the linting rules being checked. + +### Rule: required files are present The linter should check if all the required files are present. The non-exercise specific files that must be present are: @@ -24,7 +32,7 @@ Each concept listed in the `config.json` should have the following files: - `concepts//introduction.md` - `concepts//links.json` -## Rule: config.json file is valid +### Rule: config.json file is valid The `config.json` file should have the following checks: @@ -120,7 +128,7 @@ The `config.json` file should have the following checks: - The `"tags"` value must be a non-empty array of strings - The `"tags"` values must use one of the pre-defined tag values (TODO: add link to list of tags) -## Rule: config/maintainers.json file is valid +### Rule: config/maintainers.json file is valid - The file must be valid JSON - The JSON root must be an object @@ -129,7 +137,7 @@ The `config.json` file should have the following checks: - The `"maintainers"` array elements must use the correct format (TODO: specify) - There must not be duplicate maintainers -## Rule: exercises/concept/<slug>/.meta/config.json is valid +### Rule: exercises/concept/<slug>/.meta/config.json is valid - The file must be valid JSON - The JSON root must be an object @@ -165,39 +173,43 @@ The `config.json` file should have the following checks: - The `"language_versions"` key is optional - The `"language_versions"` value must be a string -## Rule: exercises/concept/<slug>/.docs/hints.md is valid +### Rule: exercises/concept/<slug>/.docs/hints.md is valid - If there are sub headings, they must start at level two - All headings must be level two headings - All headings must be either `## General` or `## X. ` where `X` matches the task number heading in the `instructions.md` - All hints must be specified as Markdown list items -## Rule: exercises/concept/<slug>/.docs/instructions.md is valid +### Rule: exercises/concept/<slug>/.docs/instructions.md is valid - If there are sub headings, they must start at level two - All tasks must start with a level two heading that starts with a number followed by a dot: `## 1. Do X` -## Rule: exercises/concept/<slug>/.docs/introduction.md is valid +### Rule: exercises/concept/<slug>/.docs/instructions.md.tpl is valid (if present) + +- Each [concept placeholders](../concept-exercises.md#docsintroductionmdtploptional)'s concept must match the `"concepts.slug"` property of one of the concepts in the track's `config.json`. + +### Rule: exercises/concept/<slug>/.docs/introduction.md is valid - If there are sub headings, they must start at level two -## Rule: exercises/shared/.docs/cli.md is valid +### Rule: exercises/shared/.docs/cli.md is valid - If there are sub headings, they must start at level two -## Rule: exercises/shared/.docs/debug.md is valid +### Rule: exercises/shared/.docs/debug.md is valid - If there are sub headings, they must start at level two -## Rule: concepts/<slug>/about.md is valid +### Rule: concepts/<slug>/about.md is valid - If there are sub headings, they must start at level two -## Rule: concepts/<slug>/introduction.md is valid +### Rule: concepts/<slug>/introduction.md is valid - If there are sub headings, they must start at level two -## Rule: concept/<slug>/links.json is valid +### Rule: concept/<slug>/links.json is valid - The file must be valid JSON - The JSON root must be an array