Fixup various aspects of the docs (#205)

jvm/example-junit5/build.gradle

@@ -19,6 +19,10 @@ dependencies {
 }
 test {
   useJUnitPlatform()
+  environment project.properties.subMap(["selfie"])
+  inputs.files(fileTree('src/test') {
+    include '**/*.ss'
+  })
 }
 apply plugin: 'com.diffplug.spotless'
 spotless {

jvm/example-kotest/build.gradle.kts

@@ -0,0 +1,17 @@
+plugins {
+  id("org.jetbrains.kotlin.jvm")
+}
+repositories {
+  mavenCentral()
+}
+dependencies {
+  testImplementation(project(":selfie-runner-kotest"))
+  testImplementation("io.kotest:kotest-runner-junit5:${project.properties["ver_KOTEST"]}")
+}
+tasks.test {
+  useJUnitPlatform()
+  environment(properties.filter { it.key == "selfie" })
+  inputs.files(fileTree("src/test") {
+    include("**/*.ss")
+  })
+}

jvm/example-kotest/src/test/kotlin/com/example/kotest/KotestConfig.kt

@@ -0,0 +1,7 @@
+package com.example.kotest
+
+import com.diffplug.selfie.kotest.SelfieExtension
+
+class KotestConfig : io.kotest.core.config.AbstractProjectConfig() {
+    override fun extensions() = listOf(SelfieExtension)
+}

jvm/example-kotest/src/test/kotlin/com/example/kotest/SmokeTest.kt

@@ -0,0 +1,12 @@
+package com.example.kotest
+
+import io.kotest.core.spec.style.FunSpec
+import com.diffplug.selfie.SelfieSuspend.expectSelfie
+
+class SmokeTest : FunSpec() {
+    init {
+        test("smoke test") {
+            expectSelfie((1 to 10).toString()).toMatchDisk()
+        }
+    }
+}

jvm/example-kotest/src/test/kotlin/com/example/kotest/SmokeTest.ss

@@ -0,0 +1,3 @@
+╔═ smoke test ═╗
+(1, 10)
+╔═ [end of file] ═╗

jvm/selfie-lib/build.gradle

@@ -2,15 +2,13 @@ plugins {
   id 'org.jetbrains.kotlin.multiplatform'
   id 'maven-publish'
 }
-
 repositories {
   mavenCentral()
 }
 ext {
   maven_name = 'selfie-lib'
   maven_desc = 'Core logic and parsing for Selfie'
 }
-
 apply from: 干.file('base/changelog.gradle')
 apply from: rootProject.file('gradle/spotless.gradle')
 kotlin {

jvm/selfie-runner-kotest/build.gradle

@@ -1,5 +1,6 @@
 plugins {
   id 'org.jetbrains.kotlin.multiplatform'
+  id 'maven-publish'
 }
 repositories {
   mavenCentral()
@@ -8,11 +9,8 @@ ext {
   maven_name = 'selfie-runner-kotest'
   maven_desc = 'Kotest test runner for Selfie'
 }
-
 apply from: 干.file('base/changelog.gradle')
 apply from: rootProject.file('gradle/spotless.gradle')
-apply plugin: 'java-library'
-
 kotlin {
   jvm {
     testRuns["test"].executionTask.configure {

jvm/settings.gradle

@@ -45,7 +45,10 @@ include 'undertest-junit-vintage'
 include 'selfie-runner-kotest'
 include 'undertest-kotest'
 
+// examples for docs and whatsuch
 if (JavaVersion.current() >= JavaVersion.VERSION_15) {
   include 'example-junit5'
 }
+include 'example-kotest'
+
 rootProject.name = 'selfie'

jvm/undertest-kotest/src/jvmTest/kotlin/kotest/KotestProjectConfig.kt

@@ -1,13 +1,7 @@
 package kotest
 
+import com.diffplug.selfie.kotest.SelfieExtension
 import io.kotest.core.config.AbstractProjectConfig
-import io.kotest.core.extensions.Extension
-// it's super weird that we can't just say `com.diffplug.selfie.kotest.SelfieExtension`
-// pretty sure it's a bug in the Kotlin multiplatform plugin
-val SelfieExtension =
-    Class.forName("com.diffplug.selfie.kotest.SelfieExtension").let {
-      it.getField("INSTANCE").get(null)
-    } as Extension
 
 object KotestProjectConfig : AbstractProjectConfig() {
   override fun extensions() = listOf(SelfieExtension)

selfie.dev/src/pages/jvm/advanced.mdx

@@ -243,4 +243,4 @@ Didn't think that adopting a bugfixed version of your internationalization lib w
 
 Testing software is a bit like tailoring a suit for an octopus. Not because the octopus needs a suit — because we need a map! And we only have one hand — better hand some pins to the octopus!
 
-*Pull requests to improve the landing page and documentation are greatly appreciated, you can find the [source code here](https://github.com/diffplug/selfie/tree/main/docs).*
+*Pull requests to improve the landing page and documentation are greatly appreciated, you can find the [source code here](https://github.com/diffplug/selfie).*

selfie.dev/src/pages/jvm/get-started.mdx

@@ -35,22 +35,47 @@ If you're using Maven, add the following dependency to your `pom.xml` file:
 <dependency>
     <groupId>com.diffplug.selfie</groupId>
     <artifactId>selfie-runner-junit5</artifactId>
-    <version>LATEST_VERSION</version>
+    <version>${ver_SELFIE}</version>
     <scope>test</scope>
 </dependency>
 ```
 
-Replace `LATEST_VERSION` with the [latest available version of selfie](https://github.com/diffplug/selfie/blob/main/jvm/CHANGELOG.md).
+Replace `ver_SELFIE` with the [latest available version of selfie](https://github.com/diffplug/selfie/blob/main/jvm/CHANGELOG.md).
 
 ### Gradle
 
 For Gradle users, add this to your `build.gradle` file:
 
-```groovy
-testImplementation 'com.diffplug.selfie:selfie-runner-junit5:LATEST_VERSION'
+```kotlin
+dependencies {
+  // ... other dependencies
+  testImplementation "com.diffplug.selfie:selfie-runner-junit5:$ver_SELFIE"
+}
+test {
+  useJUnitPlatform()
+  environment project.properties.subMap(["selfie"]) // optional, see "Overwrite everything" below
+  inputs.files(fileTree("src/test") { // optional, improves up-to-date checking
+    include "**/*.ss"
+  })
+}
 ```
 
-Again, replace `LATEST_VERSION` with the [latest available version of selfie](https://github.com/diffplug/selfie/blob/main/jvm/CHANGELOG.md).
+or this to `build.gradle.kts`:
+
+```kotlin
+dependencies {
+  testImplementation("com.diffplug.selfie:selfie-runner-junit5:${project.properties["ver_SELFIE"]}")
+}
+tasks.test {
+  useJUnitPlatform()
+  environment(properties.filter { it.key == "selfie" }) // optional, see "Overwrite everything" below
+  inputs.files(fileTree("src/test") { // optional, improves up-to-date checking
+    include("**/*.ss")
+  })
+}
+```
+
+Again, replace `ver_SELFIE` with the [latest available version of selfie](https://github.com/diffplug/selfie/blob/main/jvm/CHANGELOG.md).
 
 ## Quickstart
 
@@ -119,6 +144,24 @@ For this reason, it is critical that a CI server should always run in `readonly`
 
 When in `readonly` mode, selfie not only refuses to update any snapshots, it also fails the build if `_TODO`, `//selfieonce`, or `//SELFIEWRITE` are present in the sourcecode, even if the snapshots were correct. Writing snapshots is a strictly private affair 😏.
 
+## Overwrite everything
+
+Selfie has three modes:
+
+- `interactive`, the default mode, which we discussed in the [quickstart](#quickstart)
+- `readonly`, the default mode if `CI=true`, where no snapshots can be written
+- `overwrite`, where every snapshot is overwritten, regardless of whether it is `_TODO` or not
+
+To set the mode, you set the `selfie` or `SELFIE` environment variable or system property to either `interactive`, `readonly`, or `overwrite`. But in the vast majority of cases, it's best to leave it alone and let the defaults do their thing.
+
+```console
+[MAVEN]
+user@machine repo % mvn test -Dselfie=overwrite
+
+[GRADLE (only works if you followed the install instructions above re: environment)]
+user@machine repo % ./gradlew test -Pselfie=overwrite
+```
+
 ## Beyond toString
 
 All of the examples so far have asserted on Strings. You can also do inline literal assertions on primitive values, and disk assertions on byte arrays:
@@ -150,4 +193,6 @@ Full API documentation is available at [kdoc.selfie.dev](https://kdoc.selfie.dev
   - `interactive`, default
   - `readonly`, default if `CI` environment variable is `true`
   - `overwrite`, all snapshots can be overwritten
-- `Camera` and `Lens` are covered in the [advanced section](/jvm/advanced).
+- `Camera` and `Lens` are covered in the [advanced section](/jvm/advanced).
+
+*Pull requests to improve the landing page and documentation are greatly appreciated, you can find the [source code here](https://github.com/diffplug/selfie).*