docs: Prepare documentation for snippet checking (#172)

build.sc

@@ -156,6 +156,7 @@ object docs extends BaseModule {
       "-versions-dictionary-url", "https://iltotore.github.io/iron/versions.json",
       "-source-links:github://Iltotore/iron",
       "-revision", docRevision(),
+      "-snippet-compiler:nocompile",
       s"-social-links:github::${main.pomSettings().url}",
       s"-external-mappings:$externalMappingsFlag"
     )

docs/_docs/getting-started.md

@@ -10,13 +10,13 @@ Include Iron in your project using your preferred build tool.
 
 SBT: 
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron:version"
 ```
 

docs/_docs/modules/cats.md

@@ -10,27 +10,27 @@ This module provides typeclass instances for [Cats](https://typelevel.org/cats/)
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron-cats" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron-cats:version"
 ```
 
 ### Following examples' dependencies
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "org.typelevel" %% "cats-core" % "2.8.0"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"org.typelevel::cats-core::2.8.0"
 ```
 
@@ -42,7 +42,7 @@ These methods are similar to `refineEither` and `refineOption` defined in the co
 
 The [User example](../reference/refinement.md) now looks like this:
 
-```scala
+```scala 
 import cats.data.EitherNec
 import cats.syntax.all.*
 
@@ -54,8 +54,8 @@ case class User(name: String :| Alphanumeric, age: Int :| Positive)
 
 def createUserAcc(name: String, age: Int): EitherNec[String, User] =
 (
-    name.refineNec[Username],
-    age.refineNec[Age]
+    name.refineNec[Alphanumeric],
+    age.refineNec[Positive]
 ).parMapN(User.apply)
 
 createUserAcc("Iltotore", 18) //Right(User(Iltotore,18))
@@ -65,7 +65,15 @@ createUserAcc("Il_totore", -18) //Left(Chain(Should be alphanumeric, Should be g
 
 Or with custom messages:
 
-```scala
+```scala 
+//{
+import cats.data.EitherNec
+import cats.syntax.all.*
+
+import io.github.iltotore.iron.*
+import io.github.iltotore.iron.cats.*
+import io.github.iltotore.iron.constraint.all.*
+//}
 type Username = Alphanumeric DescribedAs "Username should be alphanumeric"
 
 type Age = Positive DescribedAs "Age should be positive"
@@ -85,10 +93,14 @@ createUserAcc("Il_totore", -18) //Left(Chain(Username should be alphanumeric, Ag
 
 Leveraging typeclass instances via Cats' syntax.
 
-```scala
+```scala 
+//{
+import io.github.iltotore.iron.*
+import io.github.iltotore.iron.constraint.all.*
+//}
 import io.github.iltotore.iron.cats.given
 
-val name1: String :| Alphanumeric = "Martin"
+val name1: String :| Alphanumeric = "Martin".refine
 val name2: String :| Alphanumeric = "George"
 val age1: Int :| Greater[0] = 60
 
@@ -103,6 +115,10 @@ Companion object created with `RefinedTypeOps` is being extended by set of funct
 
 ### Companion object
 ```scala
+//{
+import io.github.iltotore.iron.*
+import io.github.iltotore.iron.constraint.all.*
+//}
 opaque type Temperature = Double :| Positive
 object Temperature extends RefinedTypeOps[Temperature]
 ```

docs/_docs/modules/circe.md

@@ -10,29 +10,29 @@ This module provides refined types Encoder/Decoder instances for [Circe](https:/
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron-circe" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron-circe:version"
 ```
 
 ### Following examples' dependencies
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "io.circe" %% "circe-core" % "0.14.5"
 libraryDependencies += "io.circe" %% "circe-generic" % "0.14.5"
 libraryDependencies += "io.circe" %% "circe-parser" % "0.14.5"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.circe::circe-core::0.14.5"
 ivy"io.circe::circe-generic::0.14.5"
 ivy"io.circe::circe-parser::0.14.5"
@@ -42,7 +42,7 @@ ivy"io.circe::circe-parser::0.14.5"
 
 Given Encoder/Decoder for Iron enables using refined types with any Circe feature, including automatic derivation:
 
-```scala
+```scala 
 import io.circe.*
 import io.circe.parser.*
 import io.circe.syntax.*
@@ -67,7 +67,7 @@ decode[User]("""{"name":"Iltotore","age":18}""") //Right(User(Iltotore, 18))
 
 Accumulating failures is also supported using `io.circe.parser.decodeAccumulating`:
 
-```scala
+```scala 
 decodeAccumulating[User]("""{"name":"Il_totore","age":-18}""")
 //Invalid(NonEmptyList(DecodingFailure(Username should only contain alphanumeric characters., List(DownField(name))), DecodingFailure(Age should be positive, List(DownField(age)))))
 ```

docs/_docs/modules/jsoniter.md

@@ -10,28 +10,28 @@ This module provides refined types codec instances for [Jsoniter Scala](https://
 
 SBT: 
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron-jsoniter" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron-jsoniter:version"
 ```
 
 ### Following examples' dependencies
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "com.github.plokhotnyuk.jsoniter-scala" %% "jsoniter-scala-core" % "2.19.1"
 libraryDependencies += "com.github.plokhotnyuk.jsoniter-scala" %% "jsoniter-scala-macros" % "2.19.1"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-core:2.19.1"
 ivy"com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-macros:2.19.1"
 ```
@@ -40,7 +40,7 @@ ivy"com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-macros:2.19.1"
 
 Given `JsonValueCodec` for Iron enables using refined types for JSON serialization/deserialization:
 
-```scala
+```scala 
 import com.github.plokhotnyuk.jsoniter_scala.macros.*
 import com.github.plokhotnyuk.jsoniter_scala.core.*
 

docs/_docs/modules/scalacheck.md

@@ -10,13 +10,13 @@ This module provides `Arbitrary` instances for [ScalaCheck](https://scalacheck.o
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron-scalacheck" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron-scalacheck:version"
 ```
 

docs/_docs/modules/zio-json.md

@@ -10,35 +10,35 @@ This module provides refined types Encoder/Decoder instances for [ZIO JSON](http
 
 SBT: 
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron-zio-json" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron-zio-json:version"
 ```
 
 ### Following examples' dependencies
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "dev.zio" %% "zio-json" % "0.3.0"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"dev.zio::zio:0.3.0"
 ```
 
 ## Encoder/Decoder instances
 
 Given Encoder/Decoder for Iron enables using refined types for JSON serialization/deserialization:
 
-```scala
+```scala 
 import zio.json.*
 
 import io.github.iltotore.iron.*

docs/_docs/modules/zio.md

@@ -12,28 +12,28 @@ Prelude's typeclass instances already work with [[IronType|io.github.iltotore.ir
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "io.github.iltotore" %% "iron-zio" % "version"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"io.github.iltotore::iron-zio:version"
 ```
 
 ### Following examples' dependencies
 
 SBT:
 
-```scala
+```scala 
 libraryDependencies += "dev.zio" %% "zio" % "2.0.5"
 libraryDependencies += "dev.zio" %% "zio-prelude" % "1.0.0-RC16"
 ```
 
 Mill:
 
-```scala
+```scala 
 ivy"dev.zio::zio:2.0.5"
 ivy"dev.zio::zio-prelude:1.0.0-RC16"
 ```
@@ -47,7 +47,7 @@ This method is similar to `refineEither` and `refineOption` defined in the core
 The [User example](../reference/refinement.md) now looks like this:
 
 
-```scala
+```scala 
 import zio.prelude.Validation
 
 import io.github.iltotore.iron.*
@@ -77,7 +77,11 @@ createUser("Il_totore", -18) //Failure(Chunk(),NonEmptyChunk(Username should be
 Companion object created with `RefinedTypeOps` is being extended by set of functions.
 
 ### Companion object
-```scala
+```scala sc-name:Temperature.scala
+//{
+import io.github.iltotore.iron.*
+import io.github.iltotore.iron.constraint.all.*
+//}
 opaque type Temperature = Double :| Positive
 object Temperature extends RefinedTypeOps[Temperature]
 ```
@@ -88,6 +92,6 @@ object Temperature extends RefinedTypeOps[Temperature]
 ### validation
 The example below returns `ZValidation.Success` or `ZValidation.Failure`.
 
-```scala
+```scala  sc-compile-with:Temperature.scala
 Temperature.validation(x)
 ```

docs/_docs/overview.md

@@ -15,20 +15,23 @@ However, despite strong static typing, some invalid values still type check.
 
 Taking for example a User with an age:
 
-```scala
+```scala sc-name:User.scala
 case class User(age: Int)
 ```
 
 Thanks to static typing, we cannot pass values of a different type:
 
-```scala
+```scala sc-compile-with:User.scala
 User(1) //OK
+```
+
+```scala sc:fail sc-compile-with:User.scala
 User("1") //Error
 ```
 
 However, unexpected values can still be passed because `Int` contains "wrong" values for our use case:
 
-```scala
+```scala sc-compile-with:User.scala
 User(-1) //A User with a negative age?
 ```
 
@@ -38,14 +41,15 @@ To fix this caveat, you have to write an assertion/guard condition with the foll
 
 Refined types solve both problems by ensuring that constraints are checked compile time or __explicitly__ at runtime.
 
-```scala
+```scala sc-name:BetterUser.scala
 import io.github.iltotore.iron.*
 import io.github.iltotore.iron.constraint.numeric.*
 
 case class User(age: Int :| Positive)
+```
 
+```scala  sc-compile-with:BetterUser.scala
 User(1) //Compiles
-User("1") //Does not compile
 User(-1) //Does not compile
 User(-1.refine) //Compiles but fails at runtime. Useful for runtime checks such as form validation.
 //See also `refineOption` and `refineEither`