From 25a5cc9011e13b79a43f0469194ec8964986c551 Mon Sep 17 00:00:00 2001 From: Jacob Wang Date: Mon, 8 Jun 2026 18:51:17 +0100 Subject: [PATCH] move doc improvements & simplifications --- README.md | 33 +---------------- docs/docs/BestPracticeAndFAQ.md | 7 ++-- docs/docs/Derivation.md | 2 +- docs/docs/Introduction.md | 64 --------------------------------- docs/docs/index.md | 39 +++++++++++++++++--- website/docusaurus.config.js | 2 +- website/sidebars.js | 3 +- website/src/pages/index.js | 20 +++++------ 8 files changed, 49 insertions(+), 121 deletions(-) mode change 100644 => 120000 README.md delete mode 100644 docs/docs/Introduction.md diff --git a/README.md b/README.md deleted file mode 100644 index d74873e..0000000 --- a/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Difflicious - -> Diffs for human consumption - -[![Release](https://img.shields.io/maven-central/v/com.github.jatcwang/difflicious-munit_3)](https://repo1.maven.org/maven2/com/github/jatcwang/difflicious-munit_3/) - -**Difflicious** is a library that produces nice readable diffs in your tests. - -- Readable and Actionable diff results -- Flexible & Configurable diffing logic - - Ignore unimportant fields when comparing - - Compare `List`s of items independent of order - - Match `Map` entries by key and show diffs of the values -- Integration with test frameworks and popular libraries - -Hungry for some good diffs? Check out the [documentation](https://jatcwang.github.io/difflicious/)! - -# Contributing - -All contributions are welcome including suggestions and ideas. For larger changes please raise an issue -first to avoid duplicate work :) - -# Attributions - -This project takes many inspirations from - -- [diffx](https://github.com/softwaremill/diffx)'s path expression for ignoring fields -- [MUnit](https://scalameta.org/munit/)'s case class diffs - -# License - -**Apache License 2.0**. See LICENSE file. diff --git a/README.md b/README.md new file mode 120000 index 0000000..1c61f55 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +docs/docs/index.md \ No newline at end of file diff --git a/docs/docs/BestPracticeAndFAQ.md b/docs/docs/BestPracticeAndFAQ.md index 59f8c79..d44fa74 100644 --- a/docs/docs/BestPracticeAndFAQ.md +++ b/docs/docs/BestPracticeAndFAQ.md @@ -35,15 +35,12 @@ val schoolDiffer: Differ[School] = { ## Where is fully automatic derivation for `Differ`s? -Fully automatic derivation is strongly discouraged, however it might be convenient in certain debugging use-cases. - -With automatic derivation, the compiler will derive the instances **every time it is needed**. -This very frequently leads to extremely long compile times which isn't worth the few lines of code it saves you. +Fully automatic derivation is generally discouraged, however it might be convenient for quick . If you only want recursive derivation at one explicit call site, prefer `Differ.derivedDeep[T]`. It derives missing field instances recursively without enabling automatic derivation for the surrounding scope. -To enable auto-derivation add following import: +If you still want auto-derivation, add following import: for scala 2 ```scala diff --git a/docs/docs/Derivation.md b/docs/docs/Derivation.md index db41adb..d3d45ea 100644 --- a/docs/docs/Derivation.md +++ b/docs/docs/Derivation.md @@ -1,6 +1,6 @@ --- id: derivation -title: Derivation +title: Deriving Differs --- # Derivation diff --git a/docs/docs/Introduction.md b/docs/docs/Introduction.md deleted file mode 100644 index 9286d76..0000000 --- a/docs/docs/Introduction.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -id: introduction -title: Introduction ---- - -# Introduction - -**Difflicious** is a library that produces nice readable diffs in your tests. - -* **Readable** and **Actionable** diffs -* **Customizability**: supporting all kinds of tweaks you'd want to do such as ignoring fields or compare lists independent of element order. - -Here's a motivational example! - -```scala mdoc:invisible -import difflicious.Example.diffHtml -``` - -```scala mdoc:silent -import difflicious.* -import difflicious.implicits.* - -sealed trait HousePet { - def name: String -} -object HousePet { - case class Dog(name: String, age: Int) extends HousePet - case class Cat(name: String, livesLeft: Int) extends HousePet - - implicit val differ: Differ[HousePet] = Differ.derived -} - -import HousePet.{Cat, Dog} - -val petsDiffer = Differ[List[HousePet]] - .pairBy(_.name) // Match pets in the list by name for comparison - .ignoreAt(_.each.subType[Cat].livesLeft) // Don't worry about livesLeft for cats when comparing - -val petsDiff = petsDiffer.diff( - obtained = List( - Dog("Andy", 12), - Cat("Dr.Evil", 8), - Dog("Lucky", 5), - ), - expected = List( - Dog("Lucky", 6), - Cat("Dr.Evil", 9), - Cat("Andy", 12), - ) -) -``` - -And this is the diffs you will see: - -```scala mdoc:passthrough -println(diffHtml(petsDiff)) -``` - -In the example, we can see that: - -* Difflicious spots that **Andy** is not a Dog but instead a Cat!! -* The cat **Dr.Evil** is considered to be the same on both sides, because we decided to not check how many lives - the cats have left. -* A diff is produced showing us that **Lucky's** age is wrong. diff --git a/docs/docs/index.md b/docs/docs/index.md index 024513f..bee621b 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -4,18 +4,23 @@ title: Difflicious sidebar_label: Overview --- -Difflicious helps you find and compare the differences between values. +# Difflicious -[![Release](https://img.shields.io/nexus/r/com.github.jatcwang/difflicious-munit_2.13?server=https%3A%2F%2Foss.sonatype.org)](https://oss.sonatype.org/content/repositories/releases/com/github/jatcwang/difflicious-munit_2.13/) -[![(https://badges.gitter.im/gitterHQ/gitter.png)](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jatcwang/difflicious) +> Diffs for human and machine consumption -- Readable diff results -- Flexible diffing logic +[![Release](https://img.shields.io/maven-central/v/com.github.jatcwang/difflicious-munit_3)](https://repo1.maven.org/maven2/com/github/jatcwang/difflicious-munit_3/) + +**Difflicious** provides diffs for structured data in Scala, primarily for tests. + +- Readable and actionable diff results tells you where exactly your data is different +- Flexible and configurable diffing logic - Ignore unimportant fields when comparing - Compare `List`s of items independent of order - Match `Map` entries by key and show diffs of the values - Integration with test frameworks and popular libraries +Hungry for some good diffs? Check out the [documentation](https://jatcwang.github.io/difflicious/)! + # Installation If you're using the [MUnit](https://scalameta.org/munit/) test framework: @@ -33,3 +38,27 @@ If you're using [ScalaTest](https://www.scalatest.org/) test framework: // == Mill == ivy"com.github.jatcwang::difflicious-scalatest:@VERSION@" ``` + +If you're using [Weaver](https://typelevel.org/weaver-test/) test framework: +``` +// == SBT == +"com.github.jatcwang" %% "difflicious-weaver" % "@VERSION@" +// == Mill == +ivy"com.github.jatcwang::difflicious-weaver:@VERSION@" +``` + +# Contributing + +All contributions are welcome, including suggestions and ideas. For larger changes, please raise an issue +first to avoid duplicate work :) + +# Attributions + +This project takes many inspirations from: + +- [diffx](https://github.com/softwaremill/diffx)'s path expression for ignoring fields +- [MUnit](https://scalameta.org/munit/)'s case class diffs + +# License + +**Apache License 2.0**. See LICENSE file. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index ed401b1..5b479bf 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -70,7 +70,7 @@ const config = { title: 'Docs', items: [ {label: 'Quickstart', to: '/docs/quickstart'}, - {label: 'Introduction', to: '/docs/introduction'}, + {label: 'Overview', to: '/docs'}, {label: 'Configuring Differs', to: '/docs/configuring-differs'}, ], }, diff --git a/website/sidebars.js b/website/sidebars.js index 08dbd3d..5a308e5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -5,10 +5,9 @@ module.exports = { label: 'Difflicious', items: [ 'index', - 'introduction', 'quickstart', - 'derivation', 'basic-differs', + 'derivation', 'configuring-differs', { type: 'category', diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 5bfcefe..30acc58 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -33,25 +33,23 @@ export default function Home() {

{siteConfig.tagline}

- - Quickstart - - - Introduction + + Quick Start
- - Difflicious highlights the exact mismatches that caused a test failure. + + Quickly pinpoint the field, collection item, or map entry that caused + an assertion to fail. - - Ignore noisy fields, pair collection entries, and tune nested comparisons. + + Exclude fields from comparison and configure alternative pairing strategy when comparing collections. - - Use Difflicious with MUnit, ScalaTest, Weaver, Cats, and Circe. + + Integrates with popular framework and libraries such as MUnit, ScalaTest, Weaver, Cats, and Circe.