From 0741459ec899464770a3150d445567ce4af164db Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Thu, 27 Oct 2022 15:49:44 +0200 Subject: [PATCH] Tweak documentation verification tests with `Sclicheck` - 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 | 32 ++++++++++++------- .../src/test/scala/sclicheck/DocTests.scala | 15 ++++----- website/docs/guides/configuration.md | 4 +-- website/docs/guides/dependencies.md | 12 +++---- website/docs/guides/scripts.md | 2 +- 5 files changed, 36 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index db99d7b665..9f0f351ce5 100644 --- a/README.md +++ b/README.md @@ -185,21 +185,31 @@ 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 + +To check all 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.guides*' +./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. ' ``` -.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 +228,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). \ No newline at end of file +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). diff --git a/modules/docs-tests/src/test/scala/sclicheck/DocTests.scala b/modules/docs-tests/src/test/scala/sclicheck/DocTests.scala index 5733e58520..fe15ee3e37 100644 --- a/modules/docs-tests/src/test/scala/sclicheck/DocTests.scala +++ b/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", + "guides" -> 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) diff --git a/website/docs/guides/configuration.md b/website/docs/guides/configuration.md index b0855ff5cc..dac7a71ec1 100644 --- a/website/docs/guides/configuration.md +++ b/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 ``` diff --git a/website/docs/guides/dependencies.md b/website/docs/guides/dependencies.md index 84a4162627..d42e825c0a 100644 --- a/website/docs/guides/dependencies.md +++ b/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 diff --git a/website/docs/guides/scripts.md b/website/docs/guides/scripts.md index 224467651c..8980886080 100644 --- a/website/docs/guides/scripts.md +++ b/website/docs/guides/scripts.md @@ -78,7 +78,7 @@ To specify a main class when running a script, use this command: -```bash +```bash ignore scala-cli my-app --main-class main_sc ````