From eef5a0aab884e9fa158ea20adb2739bab98ac65a Mon Sep 17 00:00:00 2001
From: Thibaut Durand <durand.tibo@gmail.com>
Date: Fri, 1 Mar 2024 11:05:04 -0800
Subject: [PATCH] Update documentation (#508)

---
 docs/docs/get_started.md | 18 ++++++++++++++++++
 docs/docs/quickstart.md  | 20 ++++++++++++++++++++
 docs/docs/upgrade/0.4.md | 17 +++++++++++++++++
 docs/mkdocs.yml          |  1 +
 4 files changed, 56 insertions(+)
 create mode 100644 docs/docs/upgrade/0.4.md

diff --git a/docs/docs/get_started.md b/docs/docs/get_started.md
index ccacfec9..3befac74 100644
--- a/docs/docs/get_started.md
+++ b/docs/docs/get_started.md
@@ -75,3 +75,21 @@ install it. Finally, you can test the installation with the following command:
 ```shell
 make unit-test-cov
 ```
+
+## Testing
+
+The last version of `coola` is tested for the following package versions:
+
+| package  | tested versions    |
+|----------|--------------------|
+| `jax`    | `>=0.4,<0.5`       |
+| `numpy`  | `>=1.21,<1.27`     |
+| `pandas` | `>=1.3,<2.3`       |
+| `polars` | `>=0.18.3,<0.21`   |
+| `torch`  | `>=1.10,<2.3`      |
+| `xarray` | `>=2023.2,<2024.3` |
+
+- More information can be found in the CI workflow configuration.
+- `coola` relies on the semantic versioning (SemVer) of the packages to test the range of versions.
+- `xarray` uses [calendar versioning (CalVer)](https://calver.org/) and `coola` is tested on the
+  versions for the last year.
diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md
index d85e7419..a4424998 100644
--- a/docs/docs/quickstart.md
+++ b/docs/docs/quickstart.md
@@ -434,6 +434,26 @@ True
 
 ```
 
+Internally, [`torch.testing.assert_close`](https://pytorch.org/docs/stable/testing.html) tries to
+convert some values to tensors to compare them, which can lead to surprising results like:
+
+```pycon
+>>> import torch
+>>> torch.testing.assert_close((1, 2, 3), [1, 2, 3])
+
+```
+
+The inputs have different types: the left input is a tuple, whereas the right is a list.
+`coola` has a strict type checking and will indicate the two inputs are different:
+
+```pycon
+>>> import torch
+>>> import coola
+>>> coola.objects_are_equal((1, 2, 3), [1, 2, 3])
+False
+
+```
+
 [`numpy.testing.assert_equal`](https://numpy.org/doc/stable/reference/generated/numpy.testing.assert_equal.html)
 has different limitations.
 For example, it can work with strings but can handle only simple sequence and mapping objects
diff --git a/docs/docs/upgrade/0.4.md b/docs/docs/upgrade/0.4.md
new file mode 100644
index 00000000..bd7bfbc2
--- /dev/null
+++ b/docs/docs/upgrade/0.4.md
@@ -0,0 +1,17 @@
+# 0.3 to 0.4
+
+This page explains how to migrate from `coola` 0.3 to 0.4 because `coola` 0.4 introduces several
+non-backward compatible changes.
+
+## `objects_are_equal/allclose`
+
+The signature of the `objects_are_equal` and `objects_are_allclose` function were updated:
+
+- `object1` was renamed to `actual`
+- `object2` was renamed to `expected`
+
+The same changes were made in the associated classes to be consistent:
+
+- `BaseEqualityComparator`
+- `BaseEqualityHandler`
+- `BaseEqualityTester`
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 0b247e05..01935c61 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -38,6 +38,7 @@ nav:
       - refs/utils.md
   - Upgrade Guide:
       - upgrade/0.3.md
+      - upgrade/0.4.md
   - GitHub: https://github.com/durandtibo/coola
 
 repo_url: https://github.com/durandtibo/coola