doc: better readme + contributing.md (#40)

Co-authored-by: TomDarmon <tom.darmon@artefact.com>

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# 🧑‍💻 Contributing to track-reid
+
+## How to contribute
+
+
+### Issues, Pull Requests and Code Reviews.
+
+Issues and Pull requests templates are mandatory.
+
+At least one code review is needed to merge. Please merge your feature branches on `develop`.
+
+We try to rebase as much as possible and use squash and merge to keep a linear and condensed git history.
+
+### Getting started
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management. Poetry's doc is really good, so you should check it out if you have any questions.
+
+To install poetry:
+
+```bash
+make download-poetry
+```
+
+You can start by creating a virtual environment (conda or other) or use poetry venv(please check the Makefile first if so, as poetry venv is deactivated there). Then, to install the project dependencies, run the following command:
+
+```bash
+make install
+```
+
+To develop, you will need dev requirements too. Run:
+```bash
+make install-dev-requirements
+```
+
+!!! note "About poetry.lock"
+    `poetry.lock` is not committed deliberately, as recommended by Poetry's doc. You can read more about it [here](https://python-poetry.org/docs/basic-usage/#as-a-library-developer).
+
+### Codestyle
+
+This projects uses [Black](https://black.readthedocs.io/en/stable/), isort, ruff for codestyle. You can run the following command to format your code. It uses Pre-commit hooks to run the formatters and linters.
+
+```bash
+make format-code
+```
+
+### Docstring convention
+
+This project uses [Google docstring convention](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+
+A full example is available in [here](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+
+
+## How to release
+
+This project uses [Python Semantic Versioning](https://python-semantic-release.readthedocs.io/en/latest/automatic-releases/github-actions.html)
+and [Poetry](https://python-poetry.org/docs/cli/#build) to create releases and tags.
+
+The release process is automated through GitHub Actions. Here is the process:
+
+- Create a Pull Request from `develop` to `main`.
+- Merge the Pull Request. This must create a merge commit.
+- The merge will trigger the Release GitHub Action defined in [this workflow](.github/workflows/release.yaml).
+
+The Release GitHub Action does the following:
+
+- Checks out the code.
+- Runs the CI GitHub Action, which runs the tests and linters.
+- Runs Python Semantic Release, which takes care of version update, tag creation, and release creation.
+
+The action is triggered by any push to main.
+
+!!! tip
+    The release action will be triggered by any push to `main` only if the 'CI' job in the 'release.yaml' workflow succeeds.
+    Python Semantic Release will take care of version number update, tag creation and release creation.
+
+
+When it's done, rebase develop to keep it up to date with main.
+
+And you're done ! 🎉

Makefile

@@ -22,6 +22,11 @@ install:
 install-requirements:
 	@poetry install -n
 
+.PHONY: install-dev-requirements
+## Install Python Dependencies for development
+install-dev-requirements:
+	@poetry install -n --with dev
+
 .PHONY: update-requirements
 #help: update-requirements				- Update Python Dependencies (requirements.txt and requirements-dev.txt)
 update-requirements:

README.md

@@ -3,25 +3,17 @@
 # track-reid
 
 [![CI status](https://github.com/artefactory-fr/track-reid/actions/workflows/ci.yaml/badge.svg)](https://github.com/artefactory-fr/track-reid/actions/workflows/ci.yaml?query=branch%3Amain)
-[![Python Version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10-blue.svg)]()
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10-blue.svg)]()
 
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
 [![Linting: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 [![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-informational?logo=pre-commit&logoColor=white)](https://github.com/artefactory-fr/track-reid/blob/main/.pre-commit-config.yaml)
 </div>
 
 This Git repository is dedicated to the development of a Python library aimed at correcting the results of tracking algorithms. The primary goal of this library is to reconcile and reassign lost or misidentified IDs, ensuring a consistent and accurate tracking of objects over time.
 
-## Table of Contents
-
-- [track-reid](#track-reid)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Usage](#usage)
-  - [Documentation](#documentation)
-  - [Repository Structure](#repository-structure)
+[See the detailed documentation of this project](https://artefactory-fr.github.io/track-reid/)
 
 ## trackreid + bytetrack VS bytetrack
 <p align="center">
@@ -38,39 +30,28 @@ This Git repository is dedicated to the development of a Python library aimed at
 
 ## Installation
 
-First, install poetry:
-
+To install the library, run the following command:
 ```bash
-make download-poetry
+pip install git+https://github.com/artefactory-fr/track-reid.git@main
 ```
 
-To install the required packages in a virtual environment, run the following command:
-
-```bash
-make install
-```
-
-You can then activate the env with the following command:
-
+To install a specific version, run the following command:
 ```bash
-poetry shell
+pip install git+https://github.com/artefactory-fr/track-reid.git@x.y.z
 ```
 
-A complete list of available commands can be found using the following command:
-
-```bash
-make help
-```
 
 ## Usage
 
-For a quickstart, please refer to the documentation [here](https://artefactory-fr.github.io/track-reid/quickstart_user/). You also have at disposal a demo notebook in `notebooks/starer_kit_reid.ipynb`.
-
-Lets say you have a `dataset` iterable object, composed for each iteartion of a frame id and its associated tracking results. You can call the `ReidProcessor` update class using the following:
+Suppose you have a list of frames, a model and a tracker. You can call the `ReidProcessor` update method on each outputs of your tracker as follow:
 
 ```python
-for frame_id, tracker_output in dataset:
-    corrected_results = reid_processor.update(frame_id = frame_id,                  tracker_output=tracker_output)
+for frame_id, image_filename in enumerate(available_frames):
+    img = cv2.imread(image_filename)
+    detections = model.predict(img)
+    tracked_objects = tracker.update(detections, frame_id)
+    corrected_tracked_objects = reid_processor.update(tracked_objects, frame_id)
+
 ```
 
 At the end of the for loop, information about the correction can be retrieved using the `ReidProcessor` properties. For instance, the list of tracked object can be accessed using:
@@ -79,32 +60,4 @@ At the end of the for loop, information about the correction can be retrieved us
 reid_processor.seen_objects()
 ```
 
-## Documentation
-
-A detailed documentation of this project is available [here](https://artefactory-fr.github.io/track-reid/)
-
-To serve the documentation locally, run the following command:
-
-```bash
-mkdocs serve
-```
-
-To build it and deploy it to GitHub pages, run the following command:
-
-```bash
-make deploy_docs
-```
-
-## Repository Structure
-
-```
-.
-├── .github    <- GitHub Actions workflows and PR template
-├── bin        <- Bash files
-├── config     <- Configuration files
-├── docs       <- Documentation files (mkdocs)
-├── lib        <- Python modules
-├── notebooks  <- Jupyter notebooks
-├── secrets    <- Secret files (ignored by git)
-└── tests      <- Unit tests
-```
+For a complete example you can refer to [examples/trackreid/starter_kit_reid.ipynb](/examples/trackreid/starter_kit_reid.ipynb)

docs/quickstart_user.md

@@ -103,16 +103,21 @@ For more information on how to design custom cost and selection functions, refer
 
 ## Step 5: Run reidentifiaction process
 
-Lets say you have a `dataset` iterable object, composed for each iteartion of a frame id and its associated tracking results. You can call the [ReidProcessor](reference/reid_processor.md) update class using the following:
+Suppose you have a list of frames, a model and a tracker. You can call the `ReidProcessor` update method on each outputs of your tracker as follow:
 
 ```python
-for frame_id, tracker_output in dataset:
-    corrected_results = reid_processor.update(frame_id = frame_id,
-                                              tracker_output=tracker_output)
+for frame_id, image_filename in enumerate(available_frames):
+    img = cv2.imread(image_filename)
+    detections = model.predict(img)
+    tracked_objects = tracker.update(detections, frame_id)
+    corrected_tracked_objects = reid_processor.update(tracked_objects, frame_id)
+
 ```
 
-At the end of the for loop, information about the correction can be retrieved using the [ReidProcessor](reference/reid_processor.md) properties. For instance, the list of tracked object can be accessed using:
+At the end of the for loop, information about the correction can be retrieved using the `ReidProcessor` properties. For instance, the list of tracked object can be accessed using:
 
 ```python
 reid_processor.seen_objects()
 ```
+
+For a complete example you can refer to [examples/trackreid/starter_kit_reid.ipynb](/examples/trackreid/starter_kit_reid.ipynb)