Toolkit: MUnit, os-lib, sttp and upickle tutorials

Gemfile.lock

@@ -13,7 +13,7 @@ GEM
       execjs
     coffee-script-source (1.11.1)
     colorator (1.1.0)
-    commonmarker (0.23.8)
+    commonmarker (0.23.9)
     concurrent-ruby (1.2.2)
     dnsruby (1.61.9)
       simpleidn (~> 0.1)
@@ -219,7 +219,11 @@ GEM
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     minitest (5.18.0)
-    nokogiri (1.14.2-x86_64-linux)
+    nokogiri (1.14.3-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.14.3-x64-mingw-ucrt)
+      racc (~> 1.4)
+    nokogiri (1.14.3-x86_64-linux)
       racc (~> 1.4)
     octokit (4.25.1)
       faraday (>= 1, < 3)
@@ -263,6 +267,8 @@ GEM
     zeitwerk (2.6.7)
 
 PLATFORMS
+  arm64-darwin-22
+  x64-mingw-ucrt
   x86_64-linux
 
 DEPENDENCIES

_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
+//> using dep "org.scala-lang::toolkit-test:0.1.7"
+```
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+//> using dep "org.scalameta::munit:1.0.0-M7"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency on toolkit-test:
+```scala
+lazy val example = 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
+object example extends ScalaModule {
+  def scalaVersion = "3.2.2"
+  object test extends Tests with TestModule.Munit {
+    def ivyDeps =
+      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
+//> using toolkit "latest"
+```
+
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+//> using dep "com.lihaoyi::os-lib:0.9.1"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your `build.sbt`, you can add a 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 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
+object example extends ScalaModule {
+  def scalaVersion = "3.2.2"
+  def ivyDeps =
+    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
+//> using toolkit "latest"
+```
+
+Alternatively, you can require just a specific version of sttp:
+```scala
+//> using dep "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
+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 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
+object example extends ScalaModule {
+  def scalaVersion = "3.2.2"
+  def ivyDeps =
+    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
+//> using toolkit "latest"
+```
+
+Alternatively, you can require just a specific version of UPickle:
+```scala
+//> using dep "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
+object example extends ScalaModule {
+  def scalaVersion = "3.2.2"
+  def ivyDeps =
+    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%}

_includes/version-specific-notice.html

@@ -3,10 +3,14 @@
   <i class="fa fa-info"></i><span style="margin-left: 0.5rem">
     {% if include.language == 'scala3' %}
       This doc page is specific to Scala 3,
-      and may cover new concepts not available in Scala 2.
+      and may cover new concepts not available in Scala 2. Unless
+      otherwise stated, all the code examples in this page assume
+      you are using Scala 3.
     {% else if include.language == 'scala2' %}
       This doc page is specific to features shipped in Scala 2,
-      which have either been removed in Scala 3 or replaced by an alternative.
+      which have either been removed in Scala 3 or replaced by an
+      alternative. Unless otherwise stated, all the code examples
+      in this page assume you are using Scala 2.
     {% endif %}
   </span>
 </blockquote>

_overviews/contribute/add-guides.md

@@ -83,7 +83,7 @@ clarifications, etc.
 ## Code blocks
 
 It's common for various kinds of documents to require code examples.
-You can contribute code in a markdown document by either
+You can contribute code in a Markdown document by either
 - in-line by putting backticks around it,
 - surrounding by triple backticks,
 - or indenting it by 4 spaces, e.g.:
@@ -92,6 +92,7 @@ You can contribute code in a markdown document by either
 inline example: `val x = 23`
 
 block example:
+
 ```scala
 println("hello")
 ```
@@ -103,9 +104,31 @@ indented example:
 
 ### Scala 2 vs Scala 3
 
-Sometimes you would like to compare between Scala 2 and Scala 3 in a document, for example in
-our [Hello World][hello-world] chapter of the Scala Book. Here is an example of how you
-can generate the same tabs in markdown with the `tabs` directive and class `tabs-scala-version`:
+Our goal is to have a unified documentation that covers both Scala 2 and Scala 3. In many cases, the
+code examples are the same in both Scala 2 and Scala 3, but sometimes there are some syntactic
+differences. In some less common cases, a page may explain a concept that is new in Scala 3 and has
+no equivalent in Scala 2, or a concept that has been removed in Scala 3. In all the cases, the
+documentation should clearly "label" the code examples so that the readers know in which versions
+of Scala they are valid.
+
+The following sections explain how to properly "label" the code examples.
+
+#### Labelling the code snippets of a page documenting a concept available in both Scala 2 and Scala 3
+
+When the content of a page not specific to Scala 2 or Scala 3, like for example our
+[Hello World][hello-world] chapter of the Scala Book, the code snippets should show both the
+Scala 2 and Scala 3 syntax. We achieve this by labelling the code snippets in tabs according
+to the following rules:
+
+- if the idiomatic syntax is different in Scala 2 and Scala 3, we create two tabs,
+  “Scala 2” and “Scala 3”, showing the corresponding syntax
+- if the code snippet is idiomatic in both Scala 2 and Scala 3, we create a single tab,
+  “Scala 2 and 3”
+- if the code snippet is valid only in Scala 2 or Scala 3, we create a single tab,
+  “Scala 2 Only” or “Scala 3 Only”
+
+Here is an example of how you
+can generate such tabs in Markdown with the `tabs` directive and class `tabs-scala-version`:
 
 <!-- {% raw  %} -->
 ~~~liquid
@@ -161,6 +184,32 @@ a parameter `for=tab-group` as in this example:
 ~~~
 <!-- {% endraw  %} -->
 
+#### Labelling an entire page documenting a concept that is specific to a Scala version
+
+When the content of a page explains a concept that is new in Scala 3 and has no
+equivalent in Scala 2 (e.g. [TASTy]({% link scala3/guides/tasty-overview.md %})),
+or a concept that has been removed in Scala 3, we label the entire page instead
+of labelling each code example.
+
+We achieve this by setting a couple of a attributes in the [YAML front
+matter](https://jekyllrb.com/docs/front-matter/) of the Markdown file. For
+instance, for a page that is specific to Scala 3:
+
+~~~ yaml
+scala3: true
+versionSpecific: true
+~~~
+
+Or, for a page that is specific to Scala 2:
+
+~~~ yaml
+scala2: true
+versionSpecific: true
+~~~
+
+Please note that when the entire page is labelled, its code examples do not
+need to have tabs.
+
 ### Typechecked Examples
 
 The site build process uses [mdoc](https://scalameta.org/mdoc/) to typecheck