documentations/distance_doc.py

import streamlit as st

st.markdown(
    """
# Distance Calculator Documentation

## 1. Objective
Compute geodesic distance (meters) between two coordinate points for each row in an Excel dataset.

## 2. When to use this tool
Use this page when you need row-level distance calculation between:
- source and destination points
- serving and neighbor points
- any two coordinate pairs in the same row

## 3. Input files and accepted formats
- Required: `.xlsx` file containing coordinates for two points.

## 4. Required columns/fields
Select 4 columns from the uploaded file:
- latitude of point 1
- longitude of point 1
- latitude of point 2
- longitude of point 2

Columns must be numeric or convertible to numeric coordinates.

## 5. Step-by-step usage
1. Open `Apps > Distance Calculator`.
2. (Optional) Download sample file.
3. Upload Excel file.
4. Select the 4 coordinate columns.
5. Click `CALCULATE DISTANCE`.
6. Review the resulting table.

## 6. Outputs generated
- a new column: `distance_meters`
- interactive table with original data plus distance result

## 7. Frequent errors and fixes
- Calculation error for one or more rows.
  - Fix: check selected columns contain valid numeric latitude/longitude.
- No output after click.
  - Fix: confirm all 4 selectors are set correctly.
- Wrong distances.
  - Fix: verify coordinates are in decimal degrees (not DMS text).

## 8. Minimal reproducible example
- Input: `samples/distance.xlsx`
- Action: map point 1/point 2 columns and click `CALCULATE DISTANCE`.
- Expected result: `distance_meters` populated for each row.

## 9. Known limitations
- Only Excel `.xlsx` input is supported.
- No dedicated export button on this page.
- Invalid rows can fail row-level distance computation.

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