📝 docs(DataMart): update documentation structure

app/main.py

@@ -13,14 +13,14 @@
 from starlette.middleware.base import BaseHTTPMiddleware
 
 from app.errors import http_error_handler
+from app.routes.datamart import data_mart_router, datamart_metadata_tags
 
 from .application import app
 from .middleware import no_cache_response_header, redirect_latest, set_db_mode
 from .routes import health
 from .routes.analysis import analysis
 from .routes.assets import asset, assets
 from .routes.authentication import authentication
-from app.routes.datamart.analysis.forest_change import tree_cover_change
 from .routes.datasets import asset as version_asset
 from .routes.datasets import (
     dataset,
@@ -168,7 +168,7 @@ async def rve_error_handler(
 # Data Mart API
 ###############
 
-app.include_router(tree_cover_change.router, prefix="/datamart/analysis/forest_change/tree_cover_change")
+app.include_router(data_mart_router)
 
 ###############
 # JOB API
@@ -202,12 +202,13 @@ async def rve_error_handler(
     {"name": "Download", "description": downloads.__doc__},
     {"name": "Geostore", "description": geostore.__doc__},
     {"name": "Tasks", "description": task.__doc__},
-    {"name": "Analysis2", "description": analysis.__doc__},
+    {"name": "Analysis", "description": analysis.__doc__},
     {"name": "Job", "description": job.__doc__},
     {"name": "Health", "description": health.__doc__},
-    {"name": "Forest Change", "description": tree_cover_change.__doc__},
 ]
 
+tags_metadata.extend(datamart_metadata_tags)
+
 
 def custom_openapi():
     if app.openapi_schema:
@@ -231,7 +232,7 @@ def custom_openapi():
         {"name": "Task API", "tags": ["Tasks"]},
         {"name": "Analysis API", "tags": ["Analysis"]},
         {"name": "Health API", "tags": ["Health"]},
-        {"name": "Data Mart API", "tags": ["Forest Change"]},
+        {"name": "Data Mart API", "tags": ["Forest Change Analysis 📊"]},
     ]
 
     app.openapi_schema = openapi_schema

app/routes/datamart/__init__.py

@@ -0,0 +1,27 @@
+"""
+Data Mart APIs for Global Forest Watch (GFW) backend consumption.
+
+These APIs provide coarse-grained, tailored data services specifically designed to meet the needs of WRI frontend applications.
+The endpoints abstract away the complexities of querying datasets related to tree cover change, allowing applications to integrate and consume
+data efficiently and reliably.
+
+### Key Features:
+- Tailored queries for retrieving net tree cover change data from the GFW database.
+- Efficient data retrieval for ISO country codes and administrative regions.
+- Abstracts the SQL query generation process to simplify integration with applications.
+"""
+from fastapi import APIRouter
+
+from app.routes.datamart.analysis import analysis_router, datamart_analysis_metadata_tags
+
+datamart_metadata_tags = [
+    {"name": "Data Mart", "description": __doc__},
+]
+
+datamart_metadata_tags.extend(datamart_analysis_metadata_tags)
+
+data_mart_router = APIRouter(
+    prefix="/datamart"
+)
+
+data_mart_router.include_router(analysis_router)

app/routes/datamart/analysis/__init__.py

@@ -0,0 +1,16 @@
+from fastapi import APIRouter
+
+from app.routes.datamart.analysis.forest_change import forest_change_router, \
+    datamart_analysis_forest_change_metadata_tags
+
+datamart_analysis_metadata_tags = [
+    {"name": "Data Mart Analysis", "description": __doc__},
+]
+
+datamart_analysis_metadata_tags.extend(datamart_analysis_forest_change_metadata_tags)
+
+analysis_router = APIRouter(
+    prefix="/analysis"
+)
+
+analysis_router.include_router(forest_change_router)

app/routes/datamart/analysis/forest_change/__init__.py

@@ -0,0 +1,27 @@
+"""
+Forest Change analysis tools!
+
+**Legend:**
+
+⚠️ = _Alerts_
+
+🔥 = _Fires_
+
+🌳 = _Tree Cover Change_
+
+----
+"""
+from fastapi import APIRouter
+
+from app.routes.datamart.analysis.forest_change.tree_cover_change import tree_cover_change_router
+
+datamart_analysis_forest_change_metadata_tags = [
+    {"name": "Forest Change Analysis 📊", "description": __doc__},
+]
+
+forest_change_router = APIRouter(
+    prefix="/forest_change",
+    tags=["Forest Change Analysis 📊"]
+)
+
+forest_change_router.include_router(tree_cover_change_router)

app/routes/datamart/analysis/forest_change/tree_cover_change.py

@@ -1,18 +1,3 @@
-"""
-Data Mart APIs for Global Forest Watch (GFW) backend consumption.
-
-These APIs provide coarse-grained, tailored data services specifically designed to meet the needs of WRI frontend applications.
-The endpoints abstract away the complexities of querying datasets related to tree cover change, allowing applications to integrate and consume
-data efficiently and reliably.
-
-### Key Features:
-- Tailored queries for retrieving net tree cover change data from the GFW database.
-- Efficient data retrieval for ISO country codes and administrative regions.
-- Abstracts the SQL query generation process to simplify integration with applications.
-
-### Usage:
-Specifically, it supports the [Net change in tree cover](https://www.globalforestwatch.org/map/country/BRA/14/?mainMap=eyJzaG93QW5hbHlzaXMiOnRydWV9&map=eyJjZW50ZXIiOnsibGF0IjotMy42MjgwNjcwOTUyMDc3NDc2LCJsbmciOi01Mi40NzQ4OTk5OTk5OTczMzR9LCJ6b29tIjo2LjA1NTQ1ODQ3NjM4NDE1LCJjYW5Cb3VuZCI6ZmFsc2UsImRhdGFzZXRzIjpbeyJkYXRhc2V0IjoiTmV0LUNoYW5nZS1TVEFHSU5HIiwib3BhY2l0eSI6MSwidmlzaWJpbGl0eSI6dHJ1ZSwibGF5ZXJzIjpbImZvcmVzdC1uZXQtY2hhbmdlIl19LHsiZGF0YXNldCI6InBvbGl0aWNhbC1ib3VuZGFyaWVzIiwibGF5ZXJzIjpbImRpc3B1dGVkLXBvbGl0aWNhbC1ib3VuZGFyaWVzIiwicG9saXRpY2FsLWJvdW5kYXJpZXMiXSwib3BhY2l0eSI6MSwidmlzaWJpbGl0eSI6dHJ1ZX1dfQ%3D%3D&mapMenu=eyJtZW51U2VjdGlvbiI6ImRhdGFzZXRzIiwiZGF0YXNldENhdGVnb3J5IjoiZm9yZXN0Q2hhbmdlIn0%3D) widget
-"""
 from enum import Enum
 from typing import Optional
 
@@ -27,7 +12,10 @@
 from app.models.orm.api_keys import ApiKey
 from app.models.pydantic.base import StrictBaseModel
 
-router = APIRouter()
+
+tree_cover_change_router = APIRouter(
+    prefix="/tree_cover_change"
+)
 
 
 class Gadm(str, Enum):
@@ -163,13 +151,16 @@ async def _get_tree_cover_data(gadm_specification: GadmSpecification, api_key: A
     return await _fetch_tree_cover_data(sql_query, admin_level, api_key)
 
 
-@router.get(
-    "/v1/net_tree_cover_change",
+@tree_cover_change_router.get(
+    "/net_tree_cover_change",
     response_class=ORJSONResponse,
     response_model=NetTreeCoverChangeResponse,
-    tags=["Forest Change"],
-    summary="Retrieve net tree cover change data",
-    description="This endpoint provides data on net tree cover change by querying the Global Forest Watch (GFW) database.",
+    summary="🌳 Net Tree Cover Change",
+    description="""
+    Retrieve net tree cover change data.
+    This endpoint provides data on net tree cover change by querying the Global Forest Watch (GFW) database. 
+    Specifically, it supports the [Net change in tree cover](https://www.globalforestwatch.org/map/country/BRA/14/?mainMap=eyJzaG93QW5hbHlzaXMiOnRydWV9&map=eyJjZW50ZXIiOnsibGF0IjotMy42MjgwNjcwOTUyMDc3NDc2LCJsbmciOi01Mi40NzQ4OTk5OTk5OTczMzR9LCJ6b29tIjo2LjA1NTQ1ODQ3NjM4NDE1LCJjYW5Cb3VuZCI6ZmFsc2UsImRhdGFzZXRzIjpbeyJkYXRhc2V0IjoiTmV0LUNoYW5nZS1TVEFHSU5HIiwib3BhY2l0eSI6MSwidmlzaWJpbGl0eSI6dHJ1ZSwibGF5ZXJzIjpbImZvcmVzdC1uZXQtY2hhbmdlIl19LHsiZGF0YXNldCI6InBvbGl0aWNhbC1ib3VuZGFyaWVzIiwibGF5ZXJzIjpbImRpc3B1dGVkLXBvbGl0aWNhbC1ib3VuZGFyaWVzIiwicG9saXRpY2FsLWJvdW5kYXJpZXMiXSwib3BhY2l0eSI6MSwidmlzaWJpbGl0eSI6dHJ1ZX1dfQ%3D%3D&mapMenu=eyJtZW51U2VjdGlvbiI6ImRhdGFzZXRzIiwiZGF0YXNldENhdGVnb3J5IjoiZm9yZXN0Q2hhbmdlIn0%3D) widget.
+    """,
 )
 async def net_tree_cover_change(
         iso: str = Query(..., description="ISO code of the country or region (e.g., 'BRA' for Brazil).", example="BRA"),