documentations/gps_converter_doc.py

import streamlit as st

st.markdown(
    """
# GPS Converter Documentation

## 1. Objective
Convert coordinates between Decimal and DMS (Degree-Minute-Second) formats, from Excel files or manual input.

## 2. When to use this tool
Use this page when you need to:
- normalize coordinate format before mapping/export
- convert DMS logs into decimal values
- convert decimal values into DMS for reporting

## 3. Input files and accepted formats
Two workflows are available:
- Import Excel mode: `.xlsx` file
- Manual mode: direct coordinate input in UI

## 4. Required columns/fields
For Excel mode, select two columns from uploaded file:
- latitude column
- longitude column

For manual mode:
- Decimal -> DMS: numeric lat/lon
- DMS -> Decimal: valid DMS strings with direction (N/S/E/W)

## 5. Step-by-step usage
1. Open `Apps > GPS Converter`.
2. Choose tab: `Import Excel` or `Manual Input`.
3. In Excel mode, upload `.xlsx` and select latitude/longitude columns.
4. Select conversion type (`DMS to Decimal` or `Decimal to DMS`).
5. Click `CONVERT`.
6. Review converted table and map visualization.

## 6. Outputs generated
- converted latitude/longitude columns
- interactive grid display
- map preview for valid coordinates

## 7. Frequent errors and fixes
- Invalid decimal ranges.
  - Fix: latitude must be [-90, 90], longitude [-180, 180].
- DMS parse error.
  - Fix: use valid DMS format with direction letter.
- Empty map.
  - Fix: verify converted columns contain valid numeric coordinates.

## 8. Minimal reproducible example
- Input: `samples/Decimal_to_DMS.xlsx`
- Action: choose latitude/longitude columns, set `Decimal to DMS`, click `CONVERT`.
- Expected result: converted columns + map rendered from original decimal values.

## 9. Known limitations
- Conversion errors are strict by coordinate range.
- Map only renders rows with valid numeric coordinates.
- Mixed malformed rows may require source cleanup.

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