fix: split toolbox documentation (HEXA-1653) (#1824)

yolanfery · web-flow · commit 75eac6b64807 · 2026-05-21T15:40:45.000+02:00
diff --git a/backend/hexa/mcp/docs.py b/backend/hexa/mcp/docs.py
@@ -26,7 +26,9 @@ def _resolve_docs_dir() -> Path:
         "writing-pipelines",
         "cli",
         "sdk",
-        "toolbox",
+        "toolbox-dhis2",
+        "toolbox-iaso",
+        "toolbox-hexa",
         "notebooks-advanced",
         "static-webapps",
     }
diff --git a/backend/hexa/mcp/tests/test_help.py b/backend/hexa/mcp/tests/test_help.py
@@ -30,7 +30,9 @@ def test_unknown_topic_returns_error_with_available_topics(self):
                 "notebooks-advanced",
                 "sdk",
                 "static-webapps",
-                "toolbox",
+                "toolbox-dhis2",
+                "toolbox-hexa",
+                "toolbox-iaso",
                 "writing-pipelines",
             },
         )
@@ -55,6 +57,6 @@ def test_docstring_lists_curated_topics(self):
             "- Pass a topic name to fetch that doc page in full. Reason is optional here.\n"
             "\n"
             "\n"
-            "    Available topics: cli, notebooks-advanced, sdk, static-webapps, toolbox, writing-pipelines."
+            "    Available topics: cli, notebooks-advanced, sdk, static-webapps, toolbox-dhis2, toolbox-hexa, toolbox-iaso, writing-pipelines."
         )
         self.assertEqual(get_help_or_doc.__doc__, expected)
diff --git a/docs/en/index.md b/docs/en/index.md
@@ -95,10 +95,14 @@ If you're new to OpenHEXA, follow this learning path:
 If you're planning to develop pipelines or work with the API:
 
 - **[Writing OpenHEXA Pipelines](writing-pipelines.md)** - Create custom data workflows
+- **[Static Webapps](static-webapps.md)** - Host static web applications inside OpenHEXA
 - **[Using the OpenHEXA CLI](cli.md)** - Command-line interface
 - **[Using the OpenHEXA SDK](sdk.md)** - Python development kit
-- **[Using the OpenHEXA Toolbox](toolbox.md)** - Development utilities
+- **[Using the OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md)** - Acquire and process data from DHIS2 instances
+- **[Using the OpenHEXA Toolbox - IASO](toolbox-iaso.md)** - Fetch data from IASO
+- **[Using the OpenHEXA Toolbox - OpenHEXA Client](toolbox-hexa.md)** - Legacy GraphQL client (deprecated)
 - **[Using Notebooks in OpenHEXA](notebooks-advanced.md)** - Advanced notebook usage
+- **[API Authentication](api-authentication.md)** - Authenticate against the OpenHEXA API
 
 
 ### 👥 For administrators
diff --git a/docs/en/notebooks-advanced.md b/docs/en/notebooks-advanced.md
@@ -28,7 +28,9 @@ The OpenHEXA notebooks component works as a standard Jupyter environment, with a
 The present guide will walk you through the specificities of the OpenHEXA notebooks environment. You may also find the following two guides interesting:
 
 - [Using the OpenHEXA SDK](sdk.md): the OpenHEXA SDK is a Python library that provides building blocks and helper methods to write code on OpenHEXA
-- [Using the OpenHEXA Toolbox](toolbox.md): the OpenHEXA toolbox is a collection of utilities that can assist you in health data science integration and analysis workflows
+- [Using the OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md): Acquire and process data from DHIS2 instances
+- [Using the OpenHEXA Toolbox - IASO](toolbox-iaso.md): Fetch data from IASO
+- [Using the OpenHEXA Toolbox - OpenHEXA Client](toolbox-hexa.md): Legacy GraphQL client (deprecated)
 
 ## Using the workspace filesystem
 
diff --git a/docs/en/notebooks.md b/docs/en/notebooks.md
@@ -41,7 +41,9 @@ The OpenHEXA notebooks component works as a standard Jupyter environment, with a
 This guide walks you through the specifics of the OpenHEXA notebooks environment. You may also find these guides helpful:
 
 - [Using the OpenHEXA SDK](sdk.md): The OpenHEXA SDK is a Python library that provides building blocks and helper methods for writing code on OpenHEXA
-- [Using the OpenHEXA Toolbox](toolbox.md): The OpenHEXA Toolbox is a collection of utilities that can help you with health data science integration and analysis workflows
+- [Using the OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md): Acquire and process data from DHIS2 instances
+- [Using the OpenHEXA Toolbox - IASO](toolbox-iaso.md): Fetch data from IASO
+- [Using the OpenHEXA Toolbox - OpenHEXA Client](toolbox-hexa.md): Legacy GraphQL client (deprecated)
 
 ## Key JupyterLab features
 
diff --git a/docs/en/toolbox-dhis2.md b/docs/en/toolbox-dhis2.md
@@ -1,9 +1,6 @@
 <div class="hero-section">
-  <h1><i class="fas fa-hexagon" style="margin-right: 0.5rem;"></i>Using the OpenHEXA Toolbox</h1>
+  <h1><i class="fas fa-hexagon" style="margin-right: 0.5rem;"></i>OpenHEXA Toolbox DHIS2</h1>
 </div>
-</div>
-
-# OpenHEXA Toolbox DHIS2
 
 An utility library to acquire and process data from a DHIS2 instance.
 
@@ -444,100 +441,3 @@ True
 >>> period_from_string("2022Q3") == q1
 True
 ```
-
-
-
-# OpenHEXA Toolbox IASO
-
-Module to fetch data from IASO.
-
-## Installation
-
-``` sh
-pip install openhexa.toolbox
-```
-
-## Usage
-
-### Connect to an instance
-
-Credentials are required to initialize a connection to IASO instance. Credentials should contain the username and
-password to connect to an instance of IASO. You have as well to provide the host name to for the api to connect to:
-* Staging environment https://iaso-staging.bluesquare.org/api
-* Production environment https://iaso.bluesquare.org/api
-
-Import IASO module as:
-```
-from openhexa.toolbox.iaso import IASO
-
-iaso = IASO("https://iaso-staging.bluesquare.org","username", "password")
-```
-
-### Read data
-
-After importing IASO module, you can use provided method to fetch Projects, Organisation Units and Forms that you have
-permissions for.  
-```
-# Fetch projects 
-iaso.get_projects()
-# Fetch organisation units 
-iaso.get_org_units()
-# Fetch submitted forms filtered by form_ids passed in url parameters and with choice to fetch them as dataframe
-iaso.get_form_instances(page=1, limit=1, as_dataframe=True, 
-	dataframe_columns=["Date de création","Date de modification","Org unit"], ids=276)
-# Fetch forms filtered by organisaiton units and projects that you have permissions to
-iaso.get_forms(org_units=[781], projects=[149])
-```
-
-You can as well provide additional parameters to the method to filter on desired values as key value arguments. 
-You can have an overview on the arguments you can filter on API documentation of IASO.
-
-# OpenHEXA Toolbox - OpenHEXA Client (no longer maintained)
-
-_⚠️ We now recommend using the [SDK OpenHexa Client](sdk.md#using-the-openhexa-client) instead. It contains plenty of (typed) methods and can be semi-automatically extended by the OpenHexa team. The toolbox client will not be maintained/extended in the future_
-
-The OpenHEXA class is part of the OpenHexa toolbox, designed for interacting with the OpenHexa platform's API.
-The OpenHEXAClient module enables users to interact with the OpenHEXA backend using GraphQL syntax.
-
-## Installation
-
-``` sh
-pip install openhexa.toolbox
-```
-
-## Usage
-
-### Connect to the API
-
-To initialize the OpenHEXA class, you need to provide the server_url of the OpenHexa instance and either a username/password combination or an API token for authentication.
-Two-factor authentication should be disabled for this method.
-
-```python 
-from openhexa.toolbox.hexa import OpenHEXA
-# We can authenticate using username / password
-hexa = OpenHEXA("https://app.demo.openhexa.org", username="username",  password="password")
-
-# You can also use the token provided by OpenHEXA on the pipelines page.
-hexa = OpenHEXA("https://app.demo.openhexa.org", token="token")
-```
-
-### Play with the API
-
-After importing Hexa module, you can use provided method to fetch Projects, Organisation Units and Forms that you have
-permissions for.
-
-```python
-from openhexa.toolbox.hexa import OpenHEXA
-# Get workspaces
-workspaces = hexa.get_workspaces()
-
-# Get pipelines in a specific workspace
-workspace_slug = workspaces['workspaces']['items'][0]['slug']
-pipelines = hexa.get_pipelines(workspace_slug)
-
-# Run a pipeline
-pipeline_id = pipelines['pipelines']['items'][0]['id']
-run_response = hexa.run_pipeline(id=pipeline_id,config={}, send_notification=True)
-
-print(run_response)
-```
diff --git a/docs/en/toolbox-hexa.md b/docs/en/toolbox-hexa.md
@@ -0,0 +1,51 @@
+<div class="hero-section">
+  <h1><i class="fas fa-hexagon" style="margin-right: 0.5rem;"></i>OpenHEXA Toolbox - OpenHEXA Client (no longer maintained)</h1>
+</div>
+
+_⚠️ We now recommend using the [SDK OpenHexa Client](sdk.md#using-the-openhexa-client) instead. It contains plenty of (typed) methods and can be semi-automatically extended by the OpenHexa team. The toolbox client will not be maintained/extended in the future_
+
+The OpenHEXA class is part of the OpenHexa toolbox, designed for interacting with the OpenHexa platform's API.
+The OpenHEXAClient module enables users to interact with the OpenHEXA backend using GraphQL syntax.
+
+## Installation
+
+``` sh
+pip install openhexa.toolbox
+```
+
+## Usage
+
+### Connect to the API
+
+To initialize the OpenHEXA class, you need to provide the server_url of the OpenHexa instance and either a username/password combination or an API token for authentication.
+Two-factor authentication should be disabled for this method.
+
+```python 
+from openhexa.toolbox.hexa import OpenHEXA
+# We can authenticate using username / password
+hexa = OpenHEXA("https://app.demo.openhexa.org", username="username",  password="password")
+
+# You can also use the token provided by OpenHEXA on the pipelines page.
+hexa = OpenHEXA("https://app.demo.openhexa.org", token="token")
+```
+
+### Play with the API
+
+After importing Hexa module, you can use provided method to fetch Projects, Organisation Units and Forms that you have
+permissions for.
+
+```python
+from openhexa.toolbox.hexa import OpenHEXA
+# Get workspaces
+workspaces = hexa.get_workspaces()
+
+# Get pipelines in a specific workspace
+workspace_slug = workspaces['workspaces']['items'][0]['slug']
+pipelines = hexa.get_pipelines(workspace_slug)
+
+# Run a pipeline
+pipeline_id = pipelines['pipelines']['items'][0]['id']
+run_response = hexa.run_pipeline(id=pipeline_id,config={}, send_notification=True)
+
+print(run_response)
+```
diff --git a/docs/en/toolbox-iaso.md b/docs/en/toolbox-iaso.md
@@ -0,0 +1,46 @@
+<div class="hero-section">
+  <h1><i class="fas fa-hexagon" style="margin-right: 0.5rem;"></i>OpenHEXA Toolbox IASO</h1>
+</div>
+
+Module to fetch data from IASO.
+
+## Installation
+
+``` sh
+pip install openhexa.toolbox
+```
+
+## Usage
+
+### Connect to an instance
+
+Credentials are required to initialize a connection to IASO instance. Credentials should contain the username and
+password to connect to an instance of IASO. You have as well to provide the host name to for the api to connect to:
+* Staging environment https://iaso-staging.bluesquare.org/api
+* Production environment https://iaso.bluesquare.org/api
+
+Import IASO module as:
+```
+from openhexa.toolbox.iaso import IASO
+
+iaso = IASO("https://iaso-staging.bluesquare.org","username", "password")
+```
+
+### Read data
+
+After importing IASO module, you can use provided method to fetch Projects, Organisation Units and Forms that you have
+permissions for.  
+```
+# Fetch projects 
+iaso.get_projects()
+# Fetch organisation units 
+iaso.get_org_units()
+# Fetch submitted forms filtered by form_ids passed in url parameters and with choice to fetch them as dataframe
+iaso.get_form_instances(page=1, limit=1, as_dataframe=True, 
+	dataframe_columns=["Date de création","Date de modification","Org unit"], ids=276)
+# Fetch forms filtered by organisaiton units and projects that you have permissions to
+iaso.get_forms(org_units=[781], projects=[149])
+```
+
+You can as well provide additional parameters to the method to filter on desired values as key value arguments. 
+You can have an overview on the arguments you can filter on API documentation of IASO.
diff --git a/docs/en/writing-pipelines.md b/docs/en/writing-pipelines.md
@@ -16,7 +16,9 @@ The present guide will walk you through the creation and the deployment of an Op
 
 - [Using the OpenHEXA SDK](sdk.md): the OpenHEXA SDK is a Python library that provides building blocks and helper methods to write code on OpenHEXA
 - [Using the OpenHEXA CLI](cli.md): the OpenHEXA CLI is a command-line utility that allows you to interact with your OpenHEXA instance from your terminal
-- [Using the OpenHEXA Toolbox](toolbox.md): the OpenHEXA toolbox is a collection of utilities that can assist you in health data science integration and analysis workflows
+- [Using the OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md): Acquire and process data from DHIS2 instances
+- [Using the OpenHEXA Toolbox - IASO](toolbox-iaso.md): Fetch data from IASO
+- [Using the OpenHEXA Toolbox - OpenHEXA Client](toolbox-hexa.md): Legacy GraphQL client (deprecated)
 
 ## Quickstart
 
diff --git a/docs/fr/index.md b/docs/fr/index.md
@@ -95,10 +95,14 @@ Si vous êtes nouveau sur OpenHEXA, suivez ce parcours d'apprentissage :
 Si vous prévoyez de développer des pipelines ou de travailler avec l'API :
 
 - **[Écrire des pipelines OpenHEXA](writing-pipelines.md)** - Créez des flux de travail de données personnalisés
+- **[Webapps statiques](static-webapps.md)** - Héberger des applications web statiques dans OpenHEXA
 - **[Utiliser l'OpenHEXA CLI](cli.md)** - Interface en ligne de commande
 - **[Utiliser l'OpenHEXA SDK](sdk.md)** - Kit de développement Python
-- **[Utiliser l'OpenHEXA Toolbox](toolbox.md)** - Utilitaires de développement
+- **[Utiliser l'OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md)** - Acquérir et traiter des données depuis des instances DHIS2
+- **[Utiliser l'OpenHEXA Toolbox - IASO](toolbox-iaso.md)** - Récupérer des données depuis IASO
+- **[Utiliser l'OpenHEXA Toolbox - Client OpenHEXA](toolbox-hexa.md)** - Client GraphQL hérité (déprécié)
 - **[Utiliser les notebooks dans OpenHEXA](notebooks-advanced.md)** - Utilisation avancée des notebooks
+- **[Authentification API](api-authentication.md)** - S'authentifier auprès de l'API OpenHEXA
 
 
 ### 👥 Pour les administrateurs
diff --git a/docs/fr/notebooks-advanced.md b/docs/fr/notebooks-advanced.md
@@ -28,7 +28,9 @@ Le composant notebooks d'OpenHEXA fonctionne comme un environnement Jupyter stan
 Le présent guide vous accompagnera à travers les spécificités de l'environnement notebooks d'OpenHEXA. Vous pouvez également trouver les deux guides suivants intéressants :
 
 - [Utiliser le SDK OpenHEXA](sdk.md) : le SDK OpenHEXA est une bibliothèque Python qui fournit des blocs de construction et des méthodes utilitaires pour écrire du code sur OpenHEXA
-- [Utiliser le Toolbox OpenHEXA](toolbox.md) : le toolbox OpenHEXA est une collection d'utilitaires qui peuvent vous aider dans les workflows d'intégration et d'analyse de données de santé
+- [Utiliser l'OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md) : Acquérir et traiter des données depuis des instances DHIS2
+- [Utiliser l'OpenHEXA Toolbox - IASO](toolbox-iaso.md) : Récupérer des données depuis IASO
+- [Utiliser l'OpenHEXA Toolbox - Client OpenHEXA](toolbox-hexa.md) : Client GraphQL hérité (déprécié)
 
 ## Utiliser le système de fichiers de l'espace de travail
 
diff --git a/docs/fr/notebooks.md b/docs/fr/notebooks.md
@@ -41,7 +41,9 @@ Le composant notebooks d'OpenHEXA fonctionne comme un environnement Jupyter stan
 Ce guide vous accompagne à travers les spécificités de l'environnement notebooks d'OpenHEXA. Vous pourriez également trouver ces guides utiles :
 
 - [Utiliser l'OpenHEXA SDK](sdk.md) : Le SDK OpenHEXA est une bibliothèque Python qui fournit des blocs de construction et des méthodes d'aide pour écrire du code sur OpenHEXA
-- [Utiliser l'OpenHEXA Toolbox](toolbox.md) : L'OpenHEXA Toolbox est une collection d'utilitaires qui peuvent vous aider avec l'intégration et l'analyse de données de santé
+- [Utiliser l'OpenHEXA Toolbox - DHIS2](toolbox-dhis2.md) : Acquérir et traiter des données depuis des instances DHIS2
+- [Utiliser l'OpenHEXA Toolbox - IASO](toolbox-iaso.md) : Récupérer des données depuis IASO
+- [Utiliser l'OpenHEXA Toolbox - Client OpenHEXA](toolbox-hexa.md) : Client GraphQL hérité (déprécié)
 
 ## Fonctionnalités clés de JupyterLab
 
diff --git a/docs/fr/toolbox-dhis2.md b/docs/fr/toolbox-dhis2.md
diff --git a/docs/fr/toolbox-hexa.md b/docs/fr/toolbox-hexa.md
diff --git a/docs/fr/toolbox-iaso.md b/docs/fr/toolbox-iaso.md
diff --git a/docs/fr/writing-pipelines.md b/docs/fr/writing-pipelines.md
diff --git a/mkdocs.yml b/mkdocs.yml
