diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..bac7c58afb01d84d67488f2fbb9ee27eb7443e16
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+ configuration: docs/source/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+ install:
+ - requirements: requirements_dev.txt
diff --git a/docs/source/_static/ft06_screenshot.png b/docs/source/_static/ft06_screenshot.png
new file mode 100644
index 0000000000000000000000000000000000000000..8fd7e109d7ade5fd9b9bf0c8433edf48067932b5
Binary files /dev/null and b/docs/source/_static/ft06_screenshot.png differ
diff --git a/docs/source/_static/ta01-screenshot.png b/docs/source/_static/ta01-screenshot.png
new file mode 100644
index 0000000000000000000000000000000000000000..79e616b22d7f63e592f65bdd8724ba387b2e17bb
Binary files /dev/null and b/docs/source/_static/ta01-screenshot.png differ
diff --git a/docs/source/examples/example-gallery.md b/docs/source/examples/example-gallery.md
index 88181cd72aa90ef01dac57978a8cf8ca5962999d..194ff99171f10075d86c58267169584d81b9c913 100644
--- a/docs/source/examples/example-gallery.md
+++ b/docs/source/examples/example-gallery.md
@@ -2,12 +2,13 @@
This gallery contains a collection of code snippets together with their corresponding output, illustrating the usages of
the JSP instances with various state-of-the-art algorithms.
-sfd
```{toctree}
:caption: 'Examples:'
:maxdepth: 2
-
+graph-jsp-env_example
+graph-matrix-jsp-env_example
JSSEnv_example
+or-tools_example
```
diff --git a/docs/source/index.md b/docs/source/index.md
index f8884d5150950710059752d14e859146b7839827..f1649ae8a38a9fa538b2f14ab968fe8fd89c5f4d 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -8,7 +8,7 @@
:caption: 'Contents:'
:maxdepth: 2
-
+usage
instances-table
source-code-docs/source-code
examples/example-gallery
diff --git a/docs/source/usage.md b/docs/source/usage.md
new file mode 100644
index 0000000000000000000000000000000000000000..28d8dd9ab160f5ccb79c9d06fd34af79251db5bc
--- /dev/null
+++ b/docs/source/usage.md
@@ -0,0 +1,129 @@
+# Usage
+
+To get started, you need to install the package. You can do this by running the following command:
+
+```bash
+pip install jsp-instance-utils
+```
+Then you can import instances from the package and use them in your code. For example, to load an instance from the package.
+Here is an example of how to load the `ft06` instance from the package:
+```
+from jsp_instance_utils.instances import ft06
+from jsp_instance_utils.instances import ft06_makespan
+from jsp_instance_utils.instances import ft06_makespan_is_optimal
+```
+or you can do it in a more compact way:
+```
+from jsp_instance_utils.instances import ft06, ft06_makespan, ft06_makespan_is_optimal
+```
+
+The individual instances follow the naming in the Table of isntances.
+The `_makespan`-suffix indicates yields the lowest makespan of the instance that is known (cf. the cited literature).
+For small instances this is the optimal makespan, for larger instances it is the best known makespan.
+The `_makespan_is_optimal`-suffix indicates whether the `_makespan`-value is optimal or not.
+So `ft06` refers to the instance (in the format of this software package), `ft06_makespan` to the best known makespan, and `ft06_makespan_is_optimal` to whether the best known makespan is optimal or not.
+The `ft06` instance is a small instance with 6 jobs and 6 machines and was introduced by Fisher and Thompson in 1963.
+
+Here is another example of how to load the `ta01` instance from the package:
+```
+from jsp_instance_utils.instances import ta01, ta01_makespan, ta01_makespan_is_optimal
+```
+The `ta01` instance is a instance with 10 jobs and 10 machines and was introduced by Taillard in 1993.
+
+## Format of the Instances
+
+```{note}
+The machines are indexed starting from 0.
+```
+
+The instances in this package are represented as numpy arrays with shape `(n_jobs, n_machines, 2)`.
+here is a small example:
+
+```python
+import numpy as np
+custom_jsp_instance = np.array([
+ [
+ [0, 1, 2, 3], # job 0 (machine0, machine1, machine2, machine3)
+ [0, 2, 1, 3] # job 1 (machine0, machine1, machine2, machine3)
+ ],
+ [
+ [11, 3, 3, 12], # task durations of job 0
+ [5, 16, 7, 4] # task durations of job 1
+ ]
+])
+```
+This format is useful, because the individual matrices can easily be extracted.
+Here is an example:
+
+```python
+machine_matrix, processing_time_matrix = custom_jsp_instance
+```
+That way `machine_matrix` would be:
+
+```python
+np.array([
+ [0, 1, 2, 3],
+ [0, 2, 1, 3]
+])
+```
+and `processing_time_matrix` would be:
+
+```python
+np.array([
+ [11, 3, 3, 12],
+ [5, 16, 7, 4]
+])
+```
+
+Here is a complete runnable example of how to load the `ft06` instance from the package and how to extract the machine matrix and the processing time matrix:
+
+```python
+from jsp_instance_utils.instances import ft06, ft06_makespan, ft06_makespan_is_optimal
+
+machine_matrix, processing_times = ft06
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ft06_makespan}
+The lowest known makespan is a {'optimal' if ft06_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")
+
+```
+
+This code snippet returns the following output:
+
+
+
+Analogously, you can load the `ta01` instance from the package and extract the machine matrix and the processing time matrix:
+
+```python
+from jsp_instance_utils.instances import ta01, ta01_makespan, ta01_makespan_is_optimal
+
+machine_matrix, processing_times = ta01
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ta01_makespan}
+The lowest known makespan is a {'optimal' if ta01_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")
+```
+
+This code snippet yields the following output:
+
+
+
+## Reinforcement Learning Environments
+
+For the usage of the instances in reinforcement learning environments, we provide a wrapper class that can be used to create a reinforcement learning environment please check out the {ref}`asdasd` of this project.
diff --git a/examples/example-ft06.py b/examples/example-ft06.py
new file mode 100644
index 0000000000000000000000000000000000000000..b8dcf10b665b64ec5306b01a6a45f657a1395acd
--- /dev/null
+++ b/examples/example-ft06.py
@@ -0,0 +1,15 @@
+from jsp_instance_utils.instances import ft06, ft06_makespan, ft06_makespan_is_optimal
+
+machine_matrix, processing_times = ft06
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ft06_makespan}
+The lowest known makespan is a {'optimal' if ft06_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")
diff --git a/examples/example-ta01.py b/examples/example-ta01.py
new file mode 100644
index 0000000000000000000000000000000000000000..bea4b9a61067c03a66d347e886f1a7fb08b8bc28
--- /dev/null
+++ b/examples/example-ta01.py
@@ -0,0 +1,15 @@
+from jsp_instance_utils.instances import ta01, ta01_makespan, ta01_makespan_is_optimal
+
+machine_matrix, processing_times = ta01
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ta01_makespan}
+The lowest known makespan is a {'optimal' if ta01_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")
diff --git a/requirements_dev.txt b/requirements_dev.txt
index e8620fd8e1632873ac87e1d8573ea390d6f516fc..3117d236da94b778fc1fb628b399d0f377016e60 100644
--- a/requirements_dev.txt
+++ b/requirements_dev.txt
@@ -14,6 +14,8 @@ anyio==4.9.0
# jupyter-server
# starlette
# watchfiles
+appnope==0.1.4
+ # via ipykernel
argon2-cffi==23.1.0
# via jupyter-server
argon2-cffi-bindings==21.2.0
@@ -68,11 +70,6 @@ codecov==2.1.13
# via jssenv
colorama==0.4.6
# via
- # build
- # click
- # ipython
- # pytest
- # sphinx
# sphinx-autobuild
# tox
comm==0.2.2
@@ -357,6 +354,8 @@ pandocfilters==1.5.1
# via nbconvert
parso==0.8.4
# via jedi
+pexpect==4.9.0
+ # via ipython
pillow==11.1.0
# via
# imageio
@@ -393,6 +392,10 @@ psutil==7.0.0
# via
# ipykernel
# jssenv
+ptyprocess==0.7.0
+ # via
+ # pexpect
+ # terminado
pure-eval==0.2.3
# via stack-data
pycparser==2.22
@@ -431,17 +434,6 @@ python-json-logger==3.3.0
# via jupyter-events
pytz==2024.1
# via pandas
-pywin32==310
- # via
- # jupyter-core
- # plumbum
-pywin32-ctypes==0.2.3
- # via keyring
-pywinpty==2.0.15
- # via
- # jupyter-server
- # jupyter-server-terminals
- # terminado
pyyaml==6.0.2
# via
# jupyter-events
diff --git a/resources/ft06_screenshot.png b/resources/ft06_screenshot.png
new file mode 100644
index 0000000000000000000000000000000000000000..8fd7e109d7ade5fd9b9bf0c8433edf48067932b5
Binary files /dev/null and b/resources/ft06_screenshot.png differ