Update documentation (#508)

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.

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

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`

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