import streamlit as st

st.markdown(
    """
# Site & Sector KML Creator Documentation

## 1. Objective
Generate KML files and map previews from sector-level or site-position input data.

## 2. When to use this tool
Use this page when you need to:
- visualize telecom sectors in GIS/KML viewers
- preview sectors directly on an OpenStreetMap map before download
- plot simple site positions without sector polygons
- share sector orientation and metadata
- prepare map overlays for field/optimization teams

## 3. Input files and accepted formats
- Sector mode: one `.xlsx` file containing sector data.
- Site positions mode: one `.xlsx` or `.csv` file containing at least site, latitude, and longitude columns.

## 4. Required columns
For sector generation, the uploaded file must contain all required columns:
- `code`
- `name`
- `Azimut`
- `Longitude`
- `Latitude`
- `size`
- `color`

Any additional column is exported in sector description metadata.

For site-position generation, select the columns that represent:
- site name/code
- latitude
- longitude

Any additional column is exported in site description metadata.
The selected site icon is applied to the generated KML point placemarks.

## 5. Step-by-step usage
1. Open `Apps > Site & Sector KML Creator`.
2. (Optional) Download sample file from the page.
3. Choose `Sectors` or `Site positions`.
4. Upload your file.
5. Ensure required columns are present or select the matching site/latitude/longitude columns.
6. Review the map preview.
7. Download generated KML.

## 6. Outputs generated
- downloadable sector KML file named like `Sectors_kml_<timestamp>.kml`
- downloadable site-position KML file named like `Site_positions_<timestamp>.kml`
- interactive map preview inside the app

## 7. Frequent errors and fixes
- Missing required columns error.
  - Fix: rename columns exactly as required.
- Empty/invalid geometry in output.
  - Fix: verify `Latitude`/`Longitude` and azimuth values.
- Empty map preview.
  - Fix: verify selected latitude/longitude columns contain decimal coordinates.
- Unexpected style/color rendering.
  - Fix: validate color codes and supported color naming.

## 8. Minimal reproducible example
- Sector input: `samples/Sector_kml.xlsx`
- Action: upload file, review preview map, then download generated KML.
- Expected result: valid KML file ready for map tools and matching map preview.

Site-position minimal input:

| site | lat | lon |
| --- | --- | --- |
| S001 | 12.3 | -7.1 |

## 9. Known limitations
- Input schema is case-sensitive for required column names.
- Sector mode supports `.xlsx`.
- Site-position mode supports `.xlsx` and `.csv`.
- Invalid coordinate values may produce unusable geometry.

## 10. Version and update date
- Documentation version: 1.1
- Last update: 2026-05-02
"""
)