Add the Toolkit tutorials: MUnit, OS-Lib, UPickle and sttp (#2795)

* Init tutorials about MUnit in the Scala Toolkit * Tutorial for MUnit async tests. * Small imprvements - Use you instead of we - Remove Scala-CLI tab on Scala code - Add info about InvalidTestClassError * Add tutorial on writing assertions * +you -we * complete tutorial for running individual tests * Improve intro and “next steps” * Make munit-test-suite tutorial more concise * Adding small tutorial about testing exceptions * Remove explanations * Init tutorials about sttp * Fix munit -> sttp * Navigate from munit * Fix next page on sttp-request-body * Tutorial on uploading files * Fixing some typos * Apply suggestions from code review Co-authored-by: Adrien Piquerez <adrien.piquerez@gmail.com> * Rename dynamic urls tutorialg * Fix address & change the link * Split into lines * Fix some URLs * Add tutorial about flaky tests * Add tutorial about resource management in MUnit * Review & structure fixes to sttp tutorials * Missing .html * Fix links * Shorter sentences and other changes * Apply suggestions from code review Co-authored-by: Simon R <dev.jaca@gmail.com> * WIP: os-lib tutorial * wip * wip * wip * wip * wip * wip * wip * apply review feedback from Szymon * Reworking tutorials to have two tabs * Add scala versions to snippets * Fix Scala-cli installation * Explain testOnly * Init upicle tutorials * Reading jsons lesson * Fixes to the tutorial * More work on reading JSONs tutorial * 3 tutorials in total for upickle * More tutorials on upickle * Update links to prev/next * Fixes in the upickle tutorials * Fix links * Review JSON tutorials * Add scala versions to snippets * Tutorials on STTP x UPickle * Use real examples from the Github REST API * Add snippets for different versions of Scala * Fix pages of toolkit tutorials * Restructuring the Toolkit tutorials * Fix title of upickle-parse-json * Fix titles of upickle-parse-json and sttp-query-parameters * OS-Lib adjustments * what else can OS-Lib do * oslib: take Julien's suggestion * revise OS-Lib examples to not be REPL based * Add short introduction * Add MUnit intro * Add uPickle intro * Add uPickle what else * Add a word about why testing is useful * expand overall intro * expand introduction * Add sttp intro * Link build tool tab together * Add checks for class=tabs-build-tool * Fix function.js * fix default build tool tab * Rework introduction * Review MUnit * Review install boxes in intros * Review OS-Lib * Review upickle * Review sttp * Update nums and pages * Finishing touches * update Gemfile.lock for use on MacOS * make overall intro a bit more concise * proofread MUnit sections * proofread uPickle sections * rewrite the sttp intro pretty heavily * proofread entire sttp tutorial * avoid talk of 'install'ing libraries * fix broken link * Update versions * small fixes in munit * small fixes in uPickle * Rename files * Run mdoc in http-client tutos * Run mdoc on JSON tutorials * Run mdoc in OS tutorials * run mdoc in testing tutorials * fix mdoc * using dep, not using lib * Add toolkit in the index page and nav bar * Use toolkit lib in all build tools * Add index in intro * Use dep toolkit-test * Fix install munit --------- Co-authored-by: Sébastien Doeraene <sjrdoeraene@gmail.com> Co-authored-by: Julien Richard-Foy <julien@richard-foy.fr> Co-authored-by: Jamie Thompson <bishbashboshjt@gmail.com> Co-authored-by: Szymon Rodziewicz <szymonrodant@gmail.com> Co-authored-by: Szymon R <dev.jaca@gmail.com> Co-authored-by: Seth Tisue <seth@tisue.net>

Author: 6 people

_config.yml

@@ -192,6 +192,14 @@ defaults:
 overview-name: "Scaladoc"
 layout: multipage-overview
 permalink: "/scala3/guides/scaladoc/:title.html"
+ -
+scope:
+path: "_overviews/toolkit"
+values:
+partof: toolkit
+overview-name: "The Scala Toolkit"
+layout: multipage-overview
+permalink: "/toolkit/:title.html"
  -
 scope:
 path: "scala3"
@@ -203,6 +211,6 @@ highlighter: rouge
 permalink: /:categories/:title.html:output_ext
 baseurl:
 scala3ref: "https://docs.scala-lang.org/scala3/reference"
-exclude: ["vendor"]
+exclude: ["vendor", ".metals"]
 plugins:
  - jekyll-redirect-from

_data/doc-nav-header.yml

@@ -37,6 +37,8 @@
 url: "/tutorials/scala-on-android.html"
  - title: Scala with Maven
 url: "/tutorials/scala-with-maven.html"
+ - title: Using the Scala Toolkit
+url: "/toolkit/introduction.html"
 - title: Reference
 url: "#"
 submenu:

_includes/_markdown/install-munit.md

@@ -0,0 +1,51 @@
+{% altDetails install-info-box 'Getting MUnit' %}
+
+{% tabs munit-unit-test-1 class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//>usingdep"org.scala-lang::toolkit-test:0.1.7"
+```
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+//>usingdep"org.scalameta::munit:1.0.0-M7"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency on toolkit-test:
+```scala
+lazyvalexample= project.in(file("example"))
+ .settings(
+ scalaVersion :="3.2.2",
+ libraryDependencies +="org.scala-lang"%%"toolkit-test"%"0.1.7"%Test
+ )
+```
+Here the `Test` configuration means that the dependency is only used by the source files in `example/src/test`.
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+libraryDependencies +="org.scalameta"%%"munit"%"1.0.0-M7"%Test
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add a `test` object extending `Tests` and `TestModule.Munit`:
+```scala
+objectexampleextendsScalaModule {
+defscalaVersion="3.2.2"
+objecttestextendsTestswithTestModule.Munit {
+defivyDeps=
+Agg(
+ivy"org.scala-lang::toolkit-test:0.1.7"
+ )
+ }
+}
+```
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+ivy"org.scalameta::munit:1.0.0-M7"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/_markdown/install-os-lib.md

@@ -0,0 +1,46 @@
+{% altDetails require-info-box 'Getting OS-Lib' %}
+
+{% tabs oslib-install class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//>usingtoolkit"latest"
+```
+
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+//>usingdep"com.lihaoyi::os-lib:0.9.1"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your `build.sbt`, you can add a dependency on the toolkit:
+```scala
+lazyvalexample= project.in(file("example"))
+ .settings(
+ scalaVersion :="3.2.2",
+ libraryDependencies +="org.scala-lang"%%"toolkit"%"0.1.7"
+ )
+```
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+libraryDependencies +="com.lihaoyi"%%"os-lib"%"0.9.1"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your `build.sc` file, you can add a dependency on the Toolkit:
+```scala
+objectexampleextendsScalaModule {
+defscalaVersion="3.2.2"
+defivyDeps=
+Agg(
+ivy"org.scala-lang::toolkit:0.1.7"
+ )
+}
+```
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+ivy"com.lihaoyi::os-lib:0.9.1"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/_markdown/install-sttp.md

@@ -0,0 +1,47 @@
+{% altDetails install-info-box 'Getting sttp' %}
+
+{% tabs sttp-install-methods class=tabs-build-tool%}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//>usingtoolkit"latest"
+```
+
+Alternatively, you can require just a specific version of sttp:
+```scala
+//>usingdep"com.softwaremill.sttp.client4::core:4.0.0-M1"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add a dependency on the Toolkit:
+```scala
+lazyvalexample= project.in(file("example"))
+ .settings(
+ scalaVersion :="3.2.2",
+ libraryDependencies +="org.scala-lang"%%"toolkit"%"0.1.7"
+ )
+```
+
+Alternatively, you can require just a specific version of sttp:
+```scala
+libraryDependencies +="com.softwaremill.sttp.client4"%%"core"%"4.0.0-M1"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add a dependency on the Toolkit:
+```scala
+objectexampleextendsScalaModule {
+defscalaVersion="3.2.2"
+defivyDeps=
+Agg(
+ivy"org.scala-lang::toolkit:0.1.7"
+ )
+}
+```
+Alternatively, you can require just a specific version of sttp:
+```scala
+ivy"com.softwaremill.sttp.client4::core:4.0.0-M1"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/_markdown/install-upickle.md

@@ -0,0 +1,46 @@
+{% altDetails install-info-box 'Getting upickle' %}
+
+{% tabs upickle-install-methods class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+Using Scala CLI, you can require the entire toolkit in a single line:
+```scala
+//>usingtoolkit"latest"
+```
+
+Alternatively, you can require just a specific version of UPickle:
+```scala
+//>usingdep"com.lihaoyi::upickle:3.1.0
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency on the Toolkit:
+```scala
+lazy val example = project.in(file("example"))
+ .settings(
+ scalaVersion := "3.2.2",
+ libraryDependencies += "org.scala-lang"%%"toolkit"%"0.1.7"
+ )
+```
+Alternatively, you can require just a specific version of UPickle:
+```scala
+libraryDependencies +="com.lihaoyi"%%"upickle"%"3.1.0"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add the dependency to the upickle library:
+```scala
+objectexampleextendsScalaModule {
+defscalaVersion="3.2.2"
+defivyDeps=
+Agg(
+ivy"org.scala-lang::toolkit:0.1.7"
+ )
+}
+```
+Alternatively, you can require just a specific version of UPickle:
+```scala
+ivy"com.lihaoyi::upickle:3.1.0"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/markdown.html

@@ -0,0 +1,3 @@
+{%if include.selector%}<{{include.selector}} {%if include.classes%}class="{{include.classes}}"{%endif%} {%if include.id%}id="{{include.id}}{%endif%}">{%endif%}
+ {% capture markdown %}{% include {{include.path}} %}{% endcapture %}{{ markdown | markdownify }}
+{%if include.selector%}</{{include.selector}}>{%endif%}

_overviews/toolkit/OrderedListOfMdFiles

@@ -0,0 +1,29 @@
+introduction.md
+testing-intro.md
+testing-suite.md
+testing-run.md
+testing-run-only.md
+testing-exceptions.md
+testing-asynchronous.md
+testing-resources.md
+testing-what-else.md
+os-intro.md
+os-read-directory.md
+os-read-file.md
+os-write-file.md
+os-run-process.md
+os-what-else.md
+json-intro.md
+json-parse.md
+json-modify.md
+json-deserialize.md
+json-serialize.md
+json-files.md
+json-what-else.md
+http-client-intro.md
+http-client-request.md
+http-client-uris.md
+http-client-request-body.md
+http-client-json.md
+http-client-upload-file.md
+http-client-what-else.md

_overviews/toolkit/http-client-intro.md

@@ -0,0 +1,20 @@
+---
+title: Sending HTTP requests with sttp
+type: chapter
+description: The introduction of the sttp library
+num: 23
+previous-page: json-what-else
+next-page: http-client-request
+---
+
+sttp is a popular and feature-rich library for making HTTP requests to web servers.
+
+It provides both a synchronous API and an asynchronous `Future`-based API. It also supports WebSockets.
+
+Extensions are available that add capabilities such as streaming, logging, telemetry, and serialization.
+
+sttp offers the same APIs on all platforms (JVM, Scala.js, and Scala Native).
+
+sttp is a good choice for small synchronous scripts as well as large-scale, highly concurrent, asynchronous applications.
+
+{% include markdown.html path="_markdown/install-sttp.md" %}