Update documentation

Author: maxencefaldor

.github/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+We'd love to accept your patches and contributions to this project. When contributing to the repository, please make sure to first discuss the changes you wish to make via a [github issue](https://github.com/adaptive-intelligent-robotics/QDax/issues).
+
+After the issue is discussed and the solution is determined, you will be invited to fork the repository and create a branch to implement the solution. Once ready to be merged, you can create a [Pull Request](https://github.com/adaptive-intelligent-robotics/QDax/pulls) on github and request to merge into the branch **develop**.
+
+When implementing your contribution, there are just a few guidelines you need to follow.
+
+
+## Installing Pre-commit hooks
+
+Pre-commits hooks have been configured for this project using the [pre-commit](https://pre-commit.com/) library:
+
+- [black](https://github.com/psf/black) python formatter
+- [flake8](https://flake8.pycqa.org/en/latest/) python linter
+- [isort](https://pypi.org/project/isort/) sorts imports
+- [nbstripout](https://github.com/kynan/nbstripout) strips outputs from notebooks
+- [mypy](https://github.com/pre-commit/mirrors-mypy) checks type hints
+
+To get them going on your side, make sure to have python installed, and run the following
+commands from the root directory of this repository:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+You can then run the pre-commit hooks on all files as follows:
+
+```bash
+pre-commit run --all-files
+```
+
+
+## Coding conventions
+
+Please respect the following conventions to contribute to the code:
+
+- Use hard wrap at 88
+- Respect black, isort and flake8 conventions
+- Classes' names are Caml case (example: MyClass)
+- Functions and variables are in lower case with _ as separator (example: my_function, my_var)
+- Names are explicit: avoid mathematical notations, functions' names start with a verb
+- Use python typing library: each class and method should be typed (both for inputs and outputs)
+- Create custom types if needed
+- All classes and functions should have a docstring
+- Avoid repeating arguments and returns in docstring (should be explicit with the types) except when it is truly necessary
+- A function (or a class) does not take more than 5 arguments, if you need more create a data class
+- Avoid dictionaries to pass arguments when possible and prefer dataclasses instead
+- Repeat inputs names when calling a function: ex: compute_custom(arg1=arg1, arg2=my_arg2)
+- Use list comprehension when it is possible
+- Use f strings to add variables in strings: ex: print(f'my var value is {my_var}')
+
+
+## Commit messages
+
+Please try to follow the conventional [commit standard](https://www.conventionalcommits.org/en/v1.0.0/).
+
+
+## Merge request and code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
+
+
+## Community Guidelines
+
+This project follows
+[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).

.gitignore

@@ -1,4 +1,5 @@
 # Generated files
+public/
 *.csv
 *.pth
 *.png

.readthedocs.yaml

@@ -8,17 +8,12 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.10"
-  apt_packages:
-    - swig
+    python: "3.11"
+  jobs:
+    pre_install:
+      - curl -LsSf https://astral.sh/uv/install.sh | sh
+      - echo "$HOME/.local/bin" >> $GITHUB_PATH || true
+      - $HOME/.local/bin/uv pip install .[docs]
 
 mkdocs:
-  configuration: mkdocs.yml
-
-# Optionally declare the Python requirements required to build your docs
-python:
-  install:
-    - method: pip
-      path: .
-    - requirements: requirements.txt
-    - requirements: docs/requirements.txt
+  configuration: mkdocs.yaml

README.md

@@ -33,7 +33,23 @@ or with `pip`:
 pip install cax
 ```
 
+### Build the documentation
+
+To install the documentation toolchain and build the site:
+
+```bash
+pip install .[docs]
+mkdocs build
+```
+
+For local preview with live reload:
+
+```bash
+mkdocs serve
+```
+
 ## Basic API Usage
+
 For a full and interactive example to see how QDax works, we recommend starting with the tutorial-style [Colab notebook](./examples/mapelites.ipynb). It is an example of the MAP-Elites algorithm used to evolve a population of controllers on a chosen Brax environment (Walker by default).
 
 However, a summary of the main API usage is provided below:
@@ -128,8 +144,8 @@ repertoire.genotypes, repertoire.fitnesses, repertoire.descriptors
 
 
 ## QDax core algorithms
-QDax currently supports the following algorithms:
 
+QDax currently supports the following algorithms:
 
 | Algorithm                                                                                                                     | Example                                                                                                                                                                                         |
 |-------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -149,6 +165,7 @@ QDax currently supports the following algorithms:
 
 
 ## QDax baseline algorithms
+
 The QDax library also provides implementations for some useful baseline algorithms:
 
 | Algorithm  | Example |
@@ -160,19 +177,27 @@ The QDax library also provides implementations for some useful baseline algorith
 | [SPEA2](https://www.semanticscholar.org/paper/SPEA2%3A-Improving-the-strength-pareto-evolutionary-Zitzler-Laumanns/b13724cb54ae4171916f3f969d304b9e9752a57f) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/nsga2_spea2.ipynb) |
 | [Population Based Training (PBT)](https://arxiv.org/abs/1711.09846)                                                           | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/sac_pbt.ipynb)    |
 
+
 ## QDax Tasks
+
 The QDax library also provides numerous implementations for several standard Quality-Diversity tasks.
 
-All those implementations, and their descriptions are provided in the [tasks directory](./qdax/tasks).
+All those implementations, and their descriptions are provided in the [Tasks page](https://qdax.readthedocs.io/en/latest/api_documentation/tasks/).
+
 
 ## Contributing
+
 Issues and contributions are welcome. Please refer to the [contribution guide](https://qdax.readthedocs.io/en/latest/guides/CONTRIBUTING/) in the documentation for more details.
 
+
 ## Related Projects
+
 - [EvoJAX: Hardware-Accelerated Neuroevolution](https://github.com/google/evojax). EvoJAX is a scalable, general purpose, hardware-accelerated neuroevolution toolkit. [Paper](https://arxiv.org/abs/2202.05008)
 - [evosax: JAX-Based Evolution Strategies](https://github.com/RobertTLange/evosax)
 
+
 ## Citing QDax
+
 If you use QDax in your research and want to cite it in your work, please use:
 ```
 @article{chalumeau2024qdax,
@@ -186,6 +211,7 @@ If you use QDax in your research and want to cite it in your work, please use:
 }
 ```
 
+
 ## Contributors
 
 QDax was developed and is maintained by the [Adaptive & Intelligent Robotics Lab (AIRL)](https://www.imperial.ac.uk/adaptive-intelligent-robotics/) and [InstaDeep](https://www.instadeep.com/).

docs/api_documentation/core/aurora.md

@@ -1,6 +1,6 @@
 # AURORA class
 
-This class implement the base mechanism of AURORA. It must be used with an emitter. To get the usual AURORA algorithm, one must use the [mixing emitter](emitters.md#qdax.core.emitters.standard_emitters.MixingEmitter).
+This class implement the base mechanism of AURORA. It must be used with an emitter. To get the usual AURORA algorithm, one must use the [mixing emitter](emitters.md).
 
 The AURORA class can be used with other emitters to create variants, like [PGA-AURORA](pga_aurora.md).
 

docs/api_documentation/core/map_elites.md

@@ -1,6 +1,6 @@
 # MAP Elites class
 
-This class implement the base mechanism of MAP-Elites. It must be used with an emitter. To get the usual MAP-Elites algorithm, one must use the [mixing emitter](emitters.md#qdax.core.emitters.standard_emitters.MixingEmitter).
+This class implement the base mechanism of MAP-Elites. It must be used with an emitter. To get the usual MAP-Elites algorithm, one must use the [mixing emitter](emitters.md).
 
 The MAP-Elites class can be used with other emitters to create variants, like [PGAME](pgame.md), [DCRL-ME](dcrlme.md) [CMA-MEGA](cma_mega.md) and [OMG-MEGA](omg_mega.md).
 

docs/caveats.md

@@ -2,10 +2,14 @@
 
 Here is a few caveats one should be aware of when using QDax.
 
+
 ## Use of auto reset for Brax environments
+
 The use of `auto_reset` can be tricky and lead to problems and/or unwanted behaviors. By defaults in our examples, we set auto reset equals True, so the samples collected in the Replay Buffer are good quality samples and stay within the distribution of interest. This is particularly important in the case of PGAME, where putting auto reset to False could lead to important decrease in data efficiency and final performance.
 
+
 ## In-place replacement of state descriptors in QDTransition
+
 The state descriptor from Brax environments is stored in a dictionary. The retrievement of this data when building the QDTransition in a step is hence tricky. The state descriptor must be stored in a variable before applying a environment step, because an in-place replacement is going to occur during the step function of Brax.
 
 One should take inspiration from the `play_step` function from our examples.

docs/guides/CONTRIBUTING.md

@@ -1,66 +1,3 @@
-# Contributing
+<!-- This page includes the .github/CONTRIBUTING.md to avoid duplication. -->
 
-We'd love to accept your patches and contributions to this project. When contributing to the repository, please make sure to first discuss the changes you wish to make via a [github issue](https://github.com/adaptive-intelligent-robotics/QDax/issues).
-
-After the issue is discussed and the solution is determined, you will be invited to fork the repository and create a branch to implement the solution. Once ready to be merged, you can create a [Pull Request](https://github.com/adaptive-intelligent-robotics/QDax/pulls) on github and request to merge into the branch **develop**.
-
-When implementing your contribution, there are just a few guidelines you need to follow.
-
-## Installing Pre-commit hooks
-
-Pre-commits hooks have been configured for this project using the [pre-commit](https://pre-commit.com/) library:
-
-- [black](https://github.com/psf/black) python formatter
-- [flake8](https://flake8.pycqa.org/en/latest/) python linter
-- [isort](https://pypi.org/project/isort/) sorts imports
-- [nbstripout](https://github.com/kynan/nbstripout) strips outputs from notebooks
-- [mypy](https://github.com/pre-commit/mirrors-mypy) checks type hints
-
-To get them going on your side, make sure to have python installed, and run the following
-commands from the root directory of this repository:
-
-```bash
-pip install pre-commit
-pre-commit install
-```
-
-You can then run the pre-commit hooks on all files as follows:
-
-```bash
-pre-commit run --all-files
-```
-
-## Coding conventions
-
-Please respect the following conventions to contribute to the code:
-
-- Use hard wrap at 88
-- Respect black, isort and flake8 conventions
-- Classes' names are Caml case (example: MyClass)
-- Functions and variables are in lower case with _ as separator (example: my_function, my_var)
-- Names are explicit: avoid mathematical notations, functions' names start with a verb
-- Use python typing library: each class and method should be typed (both for inputs and outputs)
-- Create custom types if needed
-- All classes and functions should have a docstring
-- Avoid repeating arguments and returns in docstring (should be explicit with the types) except when it is truly necessary
-- A function (or a class) does not take more than 5 arguments, if you need more create a data class
-- Avoid dictionaries to pass arguments when possible and prefer dataclasses instead
-- Repeat inputs names when calling a function: ex: compute_custom(arg1=arg1, arg2=my_arg2)
-- Use list comprehension when it is possible
-- Use f strings to add variables in strings: ex: print(f'my var value is {my_var}')
-
-## Commit messages
-
-Please try to follow the conventional [commit standard](https://www.conventionalcommits.org/en/v1.0.0/).
-
-## Merge request and code reviews
-
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
-
-## Community Guidelines
-
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+--8<-- ".github/CONTRIBUTING.md"

docs/overview.md

@@ -3,23 +3,34 @@
 QDax has been designed to be modular yet flexible so it's easy for anyone to use and extend on the different state-of-the-art QD algorithms available.
 For instance, MAP-Elites is designed to work with a few modular and simple components: `container`, `emitter`, and `scoring_function`.
 
+
 ## Key concepts
+
 ### Container
+
 The `container` specifies the structure of archive of solutions to keep and the addition conditions associated with the archive.
 
+
 ### Emitter
+
 The `emitter` component is responsible for generating new solutions to be evaluated. For example, new solutions can be generated with random mutations, gradient descent, or sampling from distributions as in evolutionary strategies.
 
+
 ### Scoring Function
+
 The `scoring_function` defines the problem/task we want to solve and functions to evaluate the solutions. For example, the `scoring_function` can be used to represent standard black-box optimization tasks such as rastrigin or RL tasks.
 
+
 ## Design Choices
+
 With this modularity, a user can easily swap out any one of the components and pass it to the `MAPElites` class, avoiding having to re-implement all the steps of the algorithm.
 
 Under one layer of abstraction, users have a bit more flexibility. QDax has similarities to the simple and commonly found `ask`/`tell` interface. The `ask` function is similar to the `emit` function in QDax and the `tell` function is similar to the `update` function in QDax. Likewise, the `eval` of solutions is analogous to the `scoring function` in QDax.
 More importantly, QDax handles the archive management which is the key idea of QD algorithms and not present or needed in standard optimization algorithms or evolutionary strategies.
 
+
 ## Code Example
+
 ```python
 # Initializes repertoire and emitter state
 repertoire, emitter_state, key = map_elites.init(init_variables, centroids, key)