Make instructions append and hints consistent (#1851)

- Move some content from instructions.append.md which contain hints
  to hints.md.
- Make sure all instructions.append.md files start with the line
  `# Instructions append`.
  https://exercism.org/docs/building/tracks/practice-exercises#h-file-docs-introduction-append-md
- Make sure all hints.md files start with the line `## General`.
  https://exercism.org/docs/building/tracks/practice-exercises#h-file-docs-hints-md
- Add tests for the correct headings.

exercises/practice/accumulate/.docs/instructions.append.md → exercises/practice/accumulate/.docs/hints.md

@@ -1,4 +1,4 @@
-# Hints
+## General
 
 It may help to look at the Fn\* traits:
 [Fn](https://doc.rust-lang.org/std/ops/trait.Fn.html),

exercises/practice/binary-search/.docs/hints.md

@@ -0,0 +1,16 @@
+## General
+
+[Slices](https://doc.rust-lang.org/book/2018-edition/ch04-03-slices.html) have additionally to
+the normal element access via indexing (slice[index]) many useful functions like
+[split_at](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at) or [getting
+subslices](https://doc.rust-lang.org/std/primitive.slice.html#method.get) (slice[start..end]).
+
+You can solve this exercise by just using boring old element access via indexing, but maybe the
+other provided functions can make your code cleaner and safer.
+
+## For Bonus Points
+
+- To get your function working with all kind of elements which can be ordered,
+  have a look at the [Ord Trait](https://doc.rust-lang.org/std/cmp/trait.Ord.html).
+- To get your function working directly on Vec and Array, you can use the
+  [AsRef Trait](https://doc.rust-lang.org/std/convert/trait.AsRef.html)

exercises/practice/binary-search/.docs/instructions.append.md

@@ -6,16 +6,6 @@ Rust provides in its standard library already a
 [binary search function](https://doc.rust-lang.org/std/primitive.slice.html#method.binary_search).
 For this exercise you should not use this function but just other basic tools instead.
 
-## Hints
-
-[Slices](https://doc.rust-lang.org/book/2018-edition/ch04-03-slices.html) have additionally to
-the normal element access via indexing (slice[index]) many useful functions like
-[split_at](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at) or [getting
-subslices](https://doc.rust-lang.org/std/primitive.slice.html#method.get) (slice[start..end]).
-
-You can solve this exercise by just using boring old element access via indexing, but maybe the
-other provided functions can make your code cleaner and safer.
-
 ## For bonus points
 
 Did you get the tests passing and the code clean? If you want to, there
@@ -36,10 +26,3 @@ $ cargo test --features generic
 
 Then please share your thoughts in a comment on the submission. Did this
 experiment make the code better? Worse? Did you learn anything from it?
-
-### Hints for Bonus Points
-
-- To get your function working with all kind of elements which can be ordered,
-  have a look at the [Ord Trait](https://doc.rust-lang.org/std/cmp/trait.Ord.html).
-- To get your function working directly on Vec and Array, you can use the
-  [AsRef Trait](https://doc.rust-lang.org/std/convert/trait.AsRef.html)

exercises/practice/clock/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Rust Traits for `.to_string()`
+# Instructions append
+
+## Rust Traits for `.to_string()`
 
 You will also need to implement `.to_string()` for the `Clock` struct.
 We will be using this to display the Clock's state.

exercises/practice/decimal/.docs/hints.md

@@ -0,0 +1,5 @@
+## General
+
+- Instead of implementing arbitrary-precision arithmetic from scratch, consider building your type on top of the [num_bigint](https://crates.io/crates/num-bigint) crate.
+- You might be able to [derive](https://doc.rust-lang.org/book/2018-edition/appendix-03-derivable-traits.html) some of the required traits.
+- `Decimal` is assumed to be a signed type. You do not have to create a separate unsigned type, though you may do so as an implementation detail if you so choose.

exercises/practice/decimal/.docs/instructions.md

@@ -13,9 +13,3 @@ In Rust, the way to get these operations on custom types is to implement the rel
 # Note
 
 It would be very easy to implement this exercise by using the [bigdecimal](https://crates.io/crates/bigdecimal) crate. Don't do that; implement this yourself.
-
-# Hints
-
-- Instead of implementing arbitrary-precision arithmetic from scratch, consider building your type on top of the [num_bigint](https://crates.io/crates/num-bigint) crate.
-- You might be able to [derive](https://doc.rust-lang.org/book/2018-edition/appendix-03-derivable-traits.html) some of the required traits.
-- `Decimal` is assumed to be a signed type. You do not have to create a separate unsigned type, though you may do so as an implementation detail if you so choose.

exercises/practice/dot-dsl/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Builder pattern
+# Instructions append
+
+## Builder pattern
 
 This exercise expects you to build several structs using `builder pattern`.
 In short, this pattern allows you to split the construction function of your struct, that contains a lot of arguments, into

exercises/practice/doubly-linked-list/.docs/instructions.append.md → exercises/practice/doubly-linked-list/.docs/hints.md

@@ -1,4 +1,4 @@
-# Hints
+## General
 
 * A doubly linked does not have a clear ownership hierarchy, which is why it requires either the use
   of unsafe or abstractions for shared ownership like `Rc`. The latter has some overhead that is unnecessary

exercises/practice/forth/.docs/instructions.append.md

@@ -1,3 +1,5 @@
+# Instructions append
+
 Note the additional test case in `tests/alloc-attack.rs`. It tests against
 algorithmically inefficient implementations. Because of that, it usually times
 out online instead of outright failing, leading to a less helpful error message.

exercises/practice/hello-world/.docs/instructions.append.md

@@ -1 +1,3 @@
+# Instructions append
+
 In the Rust track, tests are run using the command `cargo test`.

exercises/practice/high-scores/.docs/instructions.append.md → exercises/practice/high-scores/.docs/hints.md

@@ -1,4 +1,4 @@
-# Hints
+## General
 
 Consider retaining a reference to `scores` in the struct - copying is not
 necessary. You will require some lifetime annotations, though.

exercises/practice/largest-series-product/.docs/instructions.append.md → exercises/practice/largest-series-product/.docs/hints.md

@@ -1,4 +1,4 @@
-# Largest Series Product in Rust
+## General
 
 These iterators may be useful, depending on your approach
 

exercises/practice/paasio/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Abstraction over Networks and Files
+# Instructions append
+
+## Abstraction over Networks and Files
 
 Network and file operations are implemented in terms of the [`io::Read`][read] and [`io::Write`][write] traits. It will therefore be necessary to implement those traits for your types.
 

exercises/practice/parallel-letter-frequency/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Parallel Letter Frequency in Rust
+# Instructions append
+
+## Parallel Letter Frequency in Rust
 
 Learn more about concurrency in Rust here:
 

exercises/practice/poker/.docs/instructions.append.md → exercises/practice/poker/.docs/hints.md

@@ -1,4 +1,4 @@
-# Hints
+## General
 
 - Ranking a list of poker hands can be considered a sorting problem.
 - Rust provides the [sort](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort) method for `Vec<T> where T: Ord`.

exercises/practice/reverse-string/.docs/instructions.append.md

@@ -1,4 +1,7 @@
-# Bonus
+# Instructions append
+
+## Bonus
+
 Test your function on this string: `uüu` and see what happens. Try to write a function that properly
 reverses this string. Hint: grapheme clusters
 

exercises/practice/rna-transcription/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Notes on Rust implementation
+# Instructions append
+
+## Notes on Rust implementation
 
 By using private fields in structs with public `new` functions returning
 `Option` or `Result` (as here with `DNA::new` & `RNA::new`), we can guarantee

exercises/practice/say/.docs/instructions.append.md

@@ -1,3 +1,4 @@
+# Instructions append
 
 ## Rust Specific Exercise Notes
 
@@ -14,6 +15,6 @@ Adding 'and' into number text has not been implemented in test cases.
 
 ### Extension
 
-Add capability of converting up to the max value for u64: 18,446,744,073,709,551,615.
+Add capability of converting up to the max value for u64: `18_446_744_073_709_551_615`.
 
 For hints at the output this should have, look at the last test case.

exercises/practice/simple-linked-list/.docs/instructions.append.md → exercises/practice/simple-linked-list/.docs/hints.md

@@ -1,4 +1,4 @@
-# Implementation Hints
+## General
 
 Do not implement the struct `SimpleLinkedList` as a wrapper around a `Vec`. Instead, allocate nodes on the heap.
 

exercises/practice/space-age/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Topics
+# Instructions append
+
+## Topics
 
 Some Rust topics you may want to read about while solving this problem:
 

exercises/practice/triangle/.docs/instructions.append.md

@@ -1,4 +1,4 @@
-# Triangle in Rust
+# Instructions append
 
 - [Result](https://doc.rust-lang.org/std/result/index.html)
 

exercises/practice/xorcism/.docs/instructions.append.md

@@ -1,4 +1,6 @@
-# Lifetime of `munge` return value
+# Instructions append
+
+## Lifetime of `munge` return value
 
 Due to the usage of the `impl Trait` feature, lifetime management may be a bit
 tricky when implementing the `munge` method. You may find it easier to write

rust-tooling/ci-tests/tests/docs_are_valid.rs

@@ -0,0 +1,32 @@
+use glob::glob;
+use utils::fs::cd_into_repo_root;
+
+// https://exercism.org/docs/building/tracks/practice-exercises#h-file-docs-hints-md
+#[test]
+fn hints_have_correct_heading() {
+    cd_into_repo_root();
+    for entry in glob("exercises/practice/*/.docs/hints.md").unwrap() {
+        let path = entry.unwrap();
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(
+            content.starts_with("## General"),
+            "incorrect heading in {}",
+            path.display()
+        )
+    }
+}
+
+// https://exercism.org/docs/building/tracks/practice-exercises#h-file-docs-introduction-append-md
+#[test]
+fn instructions_append_have_correct_heading() {
+    cd_into_repo_root();
+    for entry in glob("exercises/*/*/.docs/instructions.append.md").unwrap() {
+        let path = entry.unwrap();
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(
+            content.starts_with("# Instructions append"),
+            "incorrect heading in {}",
+            path.display()
+        )
+    }
+}