Merge pull request #7 from IFRCGo/docs

Add documentation

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material mkdocs-include-markdown-plugin
+          
+      - name: Build documentation
+        run: cd docs && mkdocs build
+        working-directory: 
+
+      - name: Deploy
+        if: github.ref == 'refs/heads/main'
+        run: cd docs && mkdocs gh-deploy --force

docs/docs/api/extension.md

@@ -0,0 +1,139 @@
+# Extension API Reference
+
+## MontyExtension
+
+The main extension class that provides Monty-specific functionality to STAC objects.
+
+```python
+class MontyExtension(Generic[T], PropertiesExtension, ExtensionManagementMixin[Union[pystac.Collection, pystac.Item]])
+```
+
+### Properties
+
+- `correlation_id` (str): A unique correlation identifier for the event
+- `country_codes` (list[str]): List of ISO 3166-1 alpha-3 country codes
+- `hazard_codes` (list[str] | None): List of hazard codes
+- `hazard_detail` (HazardDetail | None): Details about the hazard
+- `impact_detail` (ImpactDetail | None): Details about the impact
+- `episode_number` (int): Episode number for the event
+
+### Methods
+
+#### apply
+
+```python
+def apply(
+    self,
+    correlation_id: str,
+    country_codes: list[str],
+    hazard_codes: list[str] | None = None,
+) -> None
+```
+
+Applies Monty Extension properties to the extended STAC object.
+
+#### compute_and_set_correlation_id
+
+```python
+def compute_and_set_correlation_id(self, hazard_profiles: HazardProfiles) -> None
+```
+
+Computes and sets the correlation ID using the provided hazard profiles.
+
+#### ext
+
+```python
+@classmethod
+def ext(cls, obj: T, add_if_missing: bool = False) -> MontyExtension[T]
+```
+
+Creates an extension instance from a STAC object.
+
+## HazardDetail
+
+Class representing hazard details.
+
+```python
+class HazardDetail
+```
+
+### Properties
+
+- `cluster` (str): The cluster of the hazard
+- `severity_value` (float): The maximum value of the hazard
+- `severity_unit` (str): The unit of the maximum value
+- `severity_label` (str): The label of the severity
+- `estimate_type` (MontyEstimateType): The type of estimate
+
+## ImpactDetail
+
+Class representing impact details.
+
+```python
+class ImpactDetail
+```
+
+### Properties
+
+- `category` (MontyImpactExposureCategory): The impact category
+- `type` (MontyImpactType): The type of impact
+- `value` (float): The impact value
+- `unit` (str): The unit of measurement
+- `estimate_type` (MontyEstimateType): The type of estimate
+
+## Enums
+
+### MontyRoles
+
+```python
+class MontyRoles(StringEnum):
+    EVENT = "event"
+    REFERENCE = "reference"
+    SOURCE = "source"
+    HAZARD = "hazard"
+    IMPACT = "impact"
+    RESPONSE = "response"
+```
+
+### MontyEstimateType
+
+```python
+class MontyEstimateType(StringEnum):
+    PRIMARY = "primary"
+    SECONDARY = "secondary"
+    MODELLED = "modelled"
+```
+
+### MontyImpactExposureCategory
+
+Defines categories for impact exposure. Some key values include:
+
+```python
+class MontyImpactExposureCategory(StringEnum):
+    ALL_PEOPLE = "allpeop"
+    CROP = "crop"
+    BUILDINGS = "build"
+    HOSPITALS = "hosp"
+    EDUCATION_CENTERS = "educ"
+    # ... and many more
+```
+
+### MontyImpactType
+
+Defines types of impacts. Some key values include:
+
+```python
+class MontyImpactType(StringEnum):
+    UNDEFINED = "unspec"
+    DAMAGED = "dama"
+    DESTROYED = "dest"
+    DEATHS = "deat"
+    MISSING = "miss"
+    INJURED = "inju"
+    # ... and many more
+```
+
+## Constants
+
+- `SCHEMA_URI`: The URI of the Monty extension schema
+- `PREFIX`: The prefix used for Monty extension properties ("monty:")

docs/docs/api/sources.md

@@ -0,0 +1,11 @@
+# Sources API Reference
+
+The sources module provides implementations for different data sources that can be used with the Monty extension.
+
+## Available Sources
+
+- [Common](sources/common.md) - Base functionality shared across all sources
+- [GLIDE](sources/glide.md) - GLobal IDEntifier number support
+- [GDACS](sources/gdacs.md) - Global Disaster Alert and Coordination System integration
+- [EMDAT](sources/emdat.md) - Emergency Events Database integration
+

docs/docs/api/sources/common.md

@@ -0,0 +1,84 @@
+# Common
+
+The common module provides shared functionality for all sources.
+
+```python
+from pystac_monty.sources.common import BaseTransformer, MontyDataSource
+```
+
+## BaseTransformer
+
+Base class for all source transformers. Transformers are responsible for converting source data into STAC Items. Each data source (like GLIDE, GDACS, etc.) should implement its own transformer by inheriting from this base class.
+
+### Implementing a New Transformer
+
+To implement a new transformer for a data source:
+
+1. Create a new class that inherits from `BaseTransformer`
+2. Implement the `transform` method that converts source data into STAC Items
+3. Handle data validation and transformation according to your source's format
+
+Example implementation:
+
+```python
+class MySourceTransformer(BaseTransformer):
+    def __init__(self, data: MontyDataSource):
+        self.data = data
+
+    def transform(self, data: Any) -> pystac.Item:
+        # Validate input data
+        if not self._validate_data(data):
+            raise ValueError("Invalid data format")
+
+        # Transform data into STAC Item
+        item = pystac.Item(
+            id="unique-id",
+            geometry=self._extract_geometry(data),
+            bbox=self._extract_bbox(data),
+            datetime=self._extract_datetime(data),
+            properties=self._extract_properties(data)
+        )
+
+        # Add any extensions or additional metadata
+        return item
+```
+
+### Data Input Pattern
+
+Data is passed to transformers using the `MontyDataSource` class, which encapsulates:
+
+- `source_url`: The URL or identifier of where the data came from
+- `data`: The actual data to be transformed (can be any type)
+
+Example usage:
+
+```python
+source = MontyDataSource(
+    source_url="https://api.example.com/data",
+    data=raw_data
+)
+transformer = MySourceTransformer(source)
+stac_items = transformer.transform(source.get_data())
+```
+
+The `MontyDataSource` class provides a consistent interface for handling different types of input data while maintaining source information. This pattern allows transformers to:
+
+1. Access both the raw data and its source information
+2. Track data provenance
+3. Handle different data formats consistently
+
+### Key Methods
+
+When implementing a transformer, consider implementing these key methods:
+
+- `transform()`: The main method that converts source data into STAC Items
+- Data validation methods to ensure input data meets requirements
+- Helper methods for extracting specific STAC Item components (geometry, datetime, properties)
+- Methods for handling source-specific data formats or requirements
+
+The transformer should handle:
+
+- Data validation and error checking
+- Conversion of source data format to STAC Items
+- Addition of any required extensions or metadata
+- Proper handling of source URLs and data provenance

docs/docs/api/sources/emdat.md

@@ -0,0 +1,25 @@
+# EMDAT
+
+The EMDAT (Emergency Events Database) module provides functionality for working with EM-DAT data.
+
+```python
+from pystac_monty.sources.emdat import EMDATTransformer
+```
+
+## EMDATTransformer
+
+Transforms EM-DAT data into STAC Items.
+
+```python
+class EMDATTransformer(BaseTransformer):
+    """Transforms EM-DAT data into STAC Items with Monty extension."""
+    def transform(self, emdat_data: dict) -> pystac.Item:
+        """
+        Transform EM-DAT data into a STAC Item.
+        
+        Args:
+            emdat_data: Dictionary containing EM-DAT event data
+            
+        Returns:
+            pystac.Item: A STAC Item with Monty extension
+        """