Tweak documentation verification tests (#1504)

- update `README.md`
  - run docs verification tests on guides as well
  - fix some guides to prevent test failures on them (`compile`, `configuration`, `dependencies` and `scripts`)

README.md

@@ -185,21 +185,32 @@ yarn run start
 
 ### Verifying the documentation
 
-We have a built-in tool to validate `.md` files called [Sclicheck](/sclicheck/Readme.md). To check all douments (and this is what we run on CI) run:
-
-```.github/scripts/check_docs.sh```
-
-You can also check single documents or directories using
-
-
+We have a built-in tool to validate `.md` files called [Sclicheck](/sclicheck/Readme.md). 
+All `Sclicheck` tests can be run with `Mill` + `munit`: (and this is what we run on the CI, too)
+```bash
+./mill -i docs-tests.test
 ```
-.github/scripts/check_docs.sh <file> <dir>
+
+The former also includes testing gifs and `Sclicheck` itself.
+To just check the documents, run:
+```bash
+./mill -i docs-tests.test 'sclicheck.DocTests.*'
 ```
 
-To debug failing document, Sclicheck has build-in following options: `--step` (stop after each command) or `--stopAtFailure` (to stop after a failure). To debug  getting started guide run following command:
+You can also check all commands, guides or cookbooks:
+```bash
+./mill -i docs-tests.test 'sclicheck.DocTests.guide*'
+./mill -i docs-tests.test 'sclicheck.DocTests.command*'
+./mill -i docs-tests.test 'sclicheck.DocTests.cookbook*'
+```
 
+Similarly, you can check single files:
+```bash
+./mill -i docs-tests.test 'sclicheck.DocTests.<category> <doc-name>'
 ```
-.github/scripts/check_docs.sh --stopAtFailure docs/getting_started.md
+For example, to run the check on `compile.md`
+```bash
+./mill -i docs-tests.test 'sclicheck.DocTests.command compile'
 ```
 
 ## Scala CLI logos
@@ -218,4 +229,4 @@ Instructions on how to release - [Release Procedure](https://github.com/VirtusLa
 
 ## Debugging BSP server
 
-The easiest way to debug BSP sever is using `scala-cli-src` script with `--bsp-debug-port 5050` flag (the port should be unique to the workspace where BSP will be debugged). In such case BSP will be launched using local source and will run on JVM. It will also expects a debugger running in the listen mode using provided port (so the initialization of the connection can be debugged). In such case we recommend to have option to auto rerun debugging session off (so there is always a debugger instance ready to be used).
+The easiest way to debug BSP sever is using `scala-cli-src` script with `--bsp-debug-port 5050` flag (the port should be unique to the workspace where BSP will be debugged). In such case BSP will be launched using local source and will run on JVM. It will also expects a debugger running in the listen mode using provided port (so the initialization of the connection can be debugged). In such case we recommend to have option to auto rerun debugging session off (so there is always a debugger instance ready to be used).

modules/docs-tests/src/test/scala/sclicheck/DocTests.scala

@@ -1,17 +1,14 @@
 package sclicheck
 
 class DocTests extends munit.FunSuite {
-
-  val dirs = Seq(
-    "cookbook" -> os.pwd / "website" / "docs" / "cookbooks",
-    "command"  -> os.pwd / "website" / "docs" / "commands"
+  val docsRootPath: os.Path = os.pwd / "website" / "docs"
+  val dirs: Seq[(String, os.Path)] = Seq(
+    "cookbook" -> docsRootPath / "cookbooks",
+    "command"  -> docsRootPath / "commands",
+    "guide"    -> docsRootPath / "guides"
   )
 
-  val options = Options(
-    scalaCliCommand = Seq(TestUtil.scalaCliPath),
-    stopAtFailure = false,
-    step = false
-  )
+  val options: Options = Options(scalaCliCommand = Seq(TestUtil.scalaCliPath))
 
   private def containsCheck(f: os.Path): Boolean =
     os.read.lines(f)

website/docs/guides/configuration.md

@@ -23,12 +23,12 @@ scala-cli package --help
 ```
 
 As an example of command line configuration, one thing you can do with `scala-cli` command line options is to specify the Scala version:
-```bash
+```bash ignore
 scala-cli --scala 3.0.0 Test.scala
 ```
 
 Another thing you can do is to specify dependencies:
-```bash
+```bash ignore
 scala-cli --dependency org.typelevel::cats-core:2.3.0 Test.scala
 ```
 

website/docs/guides/dependencies.md

@@ -38,14 +38,14 @@ org.postgresql:postgresql:42.2.8
 
 You can add dependencies on the command line, with the `--dependency` option:
 
-```bash
+```bash ignore
 scala-cli compile Hello.scala \
   --dependency org.scala-lang.modules::scala-parallel-collections:1.0.4
 ```
 
 You can also add a URL fallback for a JAR dependency, if it can't be fetched otherwise:
 
-```bash
+```bash ignore
 scala-cli compile Hello.scala \
   -- dependency "org::name::version,url=https://url-to-the-jar"
 ```
@@ -57,14 +57,14 @@ with a different dependency version.
 
 You can also add repositories on the command-line, via `--repository`:
 
-```bash
+```bash ignore
 scala-cli compile Hello.scala \
   --dependency com.pany::util:33.1.0 --repo https://artifacts.pany.com/maven
 ```
 
 Lastly, you can also add simple JAR files as dependencies with `--jar`:
 
-```bash
+```bash ignore
 scala-cli compile Hello.scala --jar /path/to/library.jar
 ```
 
@@ -83,7 +83,7 @@ object Hello extends App {
 }
 ```
 
-```bash
+```bash ignore
 scala-cli dependency-update Hello.scala
 # Updates
 #    * com.lihaoyi::os-lib:0.7.8 -> 0.8.1
@@ -96,7 +96,7 @@ scala-cli dependency-update Hello.scala
 
 Passing `--all` to the `dependency-update` sub-command updates all dependencies in your sources.
 
-```bash
+```bash ignore
 scala-cli dependency-update Hello.scala --all
 # Updated dependency to: com.lihaoyi::os-lib:0.8.1
 # Updated dependency to: com.lihaoyi::utest:0.8.0

website/docs/guides/scripts.md

@@ -78,7 +78,7 @@ To specify a main class when running a script, use this command:
 
 <ChainedSnippets>
 
-```bash
+```bash ignore
 scala-cli my-app --main-class main_sc
 ````