Add alerthub documentation

[ranjan-stha]

• Add alerthub documentation

[emmanuelmathot]

Thank you very much @ranjan-stha for this PR with a new source 🎉

The overall structure (Collection metadata -> Data -> Event Item -> Hazard Item -> Hazard Detail) follows the established template.

Issues and gaps found

1. Missing keywords field in both Event and Hazard tables

Every other source documents the keywords field (containing human-readable country names, hazard type descriptors). The example JSON event-av.json actually includes keywords: ["Terrestrial", "Avalanche", "Meteorological & Hydrological", "RUS"], but the mapping tables don't mention it. Add a row for keywords explaining the source mapping.

2. Missing roles field in both Event and Hazard tables

All other sources explicitly document the roles property (e.g. ["source", "event"] for events, ["hazard"] for hazards). The examples include it, but the documentation tables omit it.

3. Missing Hazard Code mapping table

GDACS, GLIDE, IBTrACS, GFD, and other sources with hazard classification all include a hazard type mapping table showing how source-native categories map to the three classification systems (UNDRR-ISC 2025, GLIDE, EM-DAT). AlertHub maps alert.category and alert.event to monty:hazard_codes, but there is no mapping table explaining which AlertHub categories/events map to which codes. This is a critical gap — for example, the event-av.json shows MH0801 + AV + nat-geo-mmd-ava for avalanches, but there's no documentation of the full mapping.

4. Missing Collection: alerthub-hazards section

The doc only describes Collection: alerthub-events. Other sources that produce multiple item types (e.g., GDACS events + hazards + impacts) document each collection separately. The hazard collection alerthub-hazards.json already exists in examples but is not referenced.

5. Copy-paste error: "Link to the GDACS event details page"

In both the Event table (line 43) and the Hazard table (line 65), the via link description says "Link to the GDACS event details page" — it should say "Link to the AlertHub alert page" or similar.

6. Problematic monty:guid in event example JSON

Let's wait for the resolution of #36 to include such a new field.

7. Hazard Detail: No severity mapping table

The doc says "Five enums are mapped to a numeric value" for severity_value but doesn't list what the five severity enums are or what numeric values they map to. Other sources (GDACS, USGS) provide explicit mapping tables for their severity scales (e.g., GDACS alert scores, Richter magnitude). AlertHub should document the 5 enum values and their numeric equivalents.

8. Hazard Detail: estimate_type description says "Use a fixed value" but doesn't state the actual value

It references MontyEstimateType.PRIMARY (a code constant) instead of the actual string value "primary". Other sources document the string value directly.

9. No source data document or link to raw source example

GDACS and GLIDE both include raw source data files (e.g., 1102983-1-geteventdata-source.json) alongside the produced STAC items. The AlertHub doc describes fetching from GraphQL but doesn't include an example of the raw GraphQL response for reference.

[ranjan-stha]

Thank you very much @ranjan-stha for this PR with a new source 🎉

The overall structure (Collection metadata -> Data -> Event Item -> Hazard Item -> Hazard Detail) follows the established template.

Issues and gaps found

1. Missing keywords field in both Event and Hazard tables

Every other source documents the keywords field (containing human-readable country names, hazard type descriptors). The example JSON event-av.json actually includes keywords: ["Terrestrial", "Avalanche", "Meteorological & Hydrological", "RUS"], but the mapping tables don't mention it. Add a row for keywords explaining the source mapping.

2. Missing roles field in both Event and Hazard tables

All other sources explicitly document the roles property (e.g. ["source", "event"] for events, ["hazard"] for hazards). The examples include it, but the documentation tables omit it.

3. Missing Hazard Code mapping table

GDACS, GLIDE, IBTrACS, GFD, and other sources with hazard classification all include a hazard type mapping table showing how source-native categories map to the three classification systems (UNDRR-ISC 2025, GLIDE, EM-DAT). AlertHub maps alert.category and alert.event to monty:hazard_codes, but there is no mapping table explaining which AlertHub categories/events map to which codes. This is a critical gap — for example, the event-av.json shows MH0801 + AV + nat-geo-mmd-ava for avalanches, but there's no documentation of the full mapping.

4. Missing Collection: alerthub-hazards section

The doc only describes Collection: alerthub-events. Other sources that produce multiple item types (e.g., GDACS events + hazards + impacts) document each collection separately. The hazard collection alerthub-hazards.json already exists in examples but is not referenced.

5. Copy-paste error: "Link to the GDACS event details page"

In both the Event table (line 43) and the Hazard table (line 65), the via link description says "Link to the GDACS event details page" — it should say "Link to the AlertHub alert page" or similar.

6. Problematic monty:guid in event example JSON

Let's wait for the resolution of #36 to include such a new field.

7. Hazard Detail: No severity mapping table

The doc says "Five enums are mapped to a numeric value" for severity_value but doesn't list what the five severity enums are or what numeric values they map to. Other sources (GDACS, USGS) provide explicit mapping tables for their severity scales (e.g., GDACS alert scores, Richter magnitude). AlertHub should document the 5 enum values and their numeric equivalents.

8. Hazard Detail: estimate_type description says "Use a fixed value" but doesn't state the actual value

It references MontyEstimateType.PRIMARY (a code constant) instead of the actual string value "primary". Other sources document the string value directly.

9. No source data document or link to raw source example

GDACS and GLIDE both include raw source data files (e.g., 1102983-1-geteventdata-source.json) alongside the produced STAC items. The AlertHub doc describes fetching from GraphQL but doesn't include an example of the raw GraphQL response for reference.

Thanks Emmanuel for the detailed review. I will work on the missing parts.