diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md index 2a1c460..e8c51fe 100644 --- a/docs/cli/configuration.md +++ b/docs/cli/configuration.md @@ -20,8 +20,11 @@ meteo config [KEY VALUE] [OPTIONS] meteo config --list # Show all current settings meteo config cache_enable false # Disable caching meteo config interpolation_radius 25000 # Set interpolation radius to 25 km +meteo config stations_repo ~/weather-stations # Path to local stations repository ``` +The `stations_repo` key is used by the [contributor commands](/cli/stations/contributing#repository-path). + ## Options | Option | Description | diff --git a/docs/cli/stations/contributing/_category_.json b/docs/cli/stations/contributing/_category_.json new file mode 100644 index 0000000..80e08b9 --- /dev/null +++ b/docs/cli/stations/contributing/_category_.json @@ -0,0 +1,10 @@ +{ + "position": 5, + "label": "Contributing", + "collapsible": true, + "collapsed": true, + "link": { + "type": "doc", + "id": "cli-contributing-overview" + } +} diff --git a/docs/cli/stations/contributing/add.md b/docs/cli/stations/contributing/add.md new file mode 100644 index 0000000..622f160 --- /dev/null +++ b/docs/cli/stations/contributing/add.md @@ -0,0 +1,58 @@ +--- +title: Add Station | Meteostat CLI +sidebar_label: Add Station +sidebar_position: 2 +--- + +# Add Station + +Add a new weather station to the directory. The command creates a new JSON file in the `stations` directory of your [local repository](/cli/stations/contributing#repository-path) and assigns a unique Meteostat ID automatically. + +## Usage + +```bash +meteo station add [OPTIONS] +``` + +When called without options, the command runs interactively and prompts for all required properties. Any property passed as an option is not prompted for. + +## Examples + +```bash +meteo station add # Interactive mode +meteo station add \ + --name "Frankfurt Airport" \ + --country DE \ + --region HE \ + --lat 50.05 --lon 8.6 --elevation 111 \ + --timezone Europe/Berlin \ + --id wmo=10637 --id icao=EDDF # Non-interactive +meteo station add --name de="Frankfurt Flughafen" \ + --name en="Frankfurt Airport" ... # Multiple languages +``` + +Identifiers are passed as `KEY=VALUE` pairs and stored in the station's `identifiers` object. Any key is accepted, so you can add identifiers for national networks or other data sources in addition to common ones like `wmo`, `icao`, `iata`, `national` and `ghcn`. + +Before the file is written, the new station is [validated](validate.md) and checked against existing stations for [potential duplicates](duplicates.md). If a likely duplicate is found, you are asked to confirm. + +On success, the command prints the ID and path of the new station file: + +```text +Created station 0A1B2 (stations/0A1B2.json) +``` + +## Options + +| Option | Short | Description | +| ------------- | ----- | ------------------------------------------------------------------------------------------------------------- | +| `--name` | `-n` | Station name. Use `LANG=NAME` to set a localized name (repeatable). A plain value is stored as English (`en`) | +| `--country` | `-c` | ISO 3166-1 alpha-2 country code | +| `--region` | | ISO 3166-2 state or region code | +| `--lat` | | Latitude in decimal degrees | +| `--lon` | | Longitude in decimal degrees | +| `--elevation` | `-e` | Elevation in meters | +| `--timezone` | `-t` | IANA time zone (e.g. `Europe/Berlin`) | +| `--id` | `-i` | Station identifier as `KEY=VALUE` (e.g. `wmo=10637`, `icao=EDDF`). Any key is accepted (repeatable) | +| `--yes` | `-y` | Don't prompt; fail if a required property is missing and skip duplicate confirmation | +| `--dry-run` | | Print the resulting JSON without writing any file | +| `--repo` | | Path to the stations repository (overrides `stations_repo`) | diff --git a/docs/cli/stations/contributing/build.md b/docs/cli/stations/contributing/build.md new file mode 100644 index 0000000..3729ba3 --- /dev/null +++ b/docs/cli/stations/contributing/build.md @@ -0,0 +1,38 @@ +--- +title: Build Database | Meteostat CLI +sidebar_label: Build Database +sidebar_position: 7 +--- + +# Build Database + +Build a SQLite database from the station files in your [local repository](/cli/stations/contributing#repository-path). The resulting file has the same structure as the [official stations database](/data/weather-stations#database), which makes it easy to test your changes locally before submitting them. + +## Usage + +```bash +meteo station build [OPTIONS] +``` + +By default, the database is written to `stations.db` in the root of the stations repository. Existing files are overwritten. + +## Examples + +```bash +meteo station build # Build stations.db in the repository root +meteo station build --output ~/stations.db # Custom output path +``` + +## Options + +| Option | Short | Description | +| ------------------- | ----- | ---------------------------------------------------------------- | +| `--output` | `-o` | Output file path (default: `stations.db` in the repository root) | +| `--skip-validation` | | Don't [validate](validate.md) stations before building | +| `--repo` | | Path to the stations repository (overrides `stations_repo`) | + +:::info + +Stations which fail validation are skipped and reported unless `--skip-validation` is set. + +::: diff --git a/docs/cli/stations/contributing/delete.md b/docs/cli/stations/contributing/delete.md new file mode 100644 index 0000000..d999dad --- /dev/null +++ b/docs/cli/stations/contributing/delete.md @@ -0,0 +1,37 @@ +--- +title: Delete Station | Meteostat CLI +sidebar_label: Delete Station +sidebar_position: 4 +--- + +# Delete Station + +Remove a weather station from your [local repository](/cli/stations/contributing#repository-path). + +## Usage + +```bash +meteo station delete ID [OPTIONS] +``` + +The command shows the station's metadata and asks for confirmation before removing its JSON file. + +## Examples + +```bash +meteo station delete 0A1B2 # Delete a station (asks for confirmation) +meteo station delete 0A1B2 --yes # Delete without confirmation +``` + +:::warning + +Only delete stations which were added by mistake or are exact [duplicates](duplicates.md). If a station has simply stopped reporting, **do not delete it** so historical data remains available. + +::: + +## Options + +| Option | Short | Description | +| -------- | ----- | ----------------------------------------------------------- | +| `--yes` | `-y` | Skip the confirmation prompt | +| `--repo` | | Path to the stations repository (overrides `stations_repo`) | diff --git a/docs/cli/stations/contributing/duplicates.md b/docs/cli/stations/contributing/duplicates.md new file mode 100644 index 0000000..fda96d0 --- /dev/null +++ b/docs/cli/stations/contributing/duplicates.md @@ -0,0 +1,52 @@ +--- +title: Find Duplicates | Meteostat CLI +sidebar_label: Find Duplicates +sidebar_position: 6 +--- + +# Find Duplicates + +Find potential duplicate stations in your [local repository](/cli/stations/contributing#repository-path). Two stations are reported as potential duplicates if they share an identifier (e.g. WMO or ICAO ID) or are located close to each other and have similar names. + +## Usage + +```bash +meteo station duplicates [OPTIONS] +``` + +## Examples + +```bash +meteo station duplicates # Check the whole directory +meteo station duplicates --country DE # Only check stations in Germany +meteo station duplicates --id 10637 # Find duplicates of a specific station +meteo station duplicates --radius 500 # Only match stations within 500 m +meteo station duplicates --format json # JSON output +``` + +## Output + +Each row represents a pair of stations along with their distance and the reasons why they were matched: + +```text +station_a station_b distance reasons +10637 0A1B2 120 wmo, name +10635 D4X9K 340 location, name +``` + +Review each pair carefully. If two records describe the same station, merge the relevant information into one using [`edit`](edit.md) and remove the other one using [`delete`](delete.md). + +## Options + +| Option | Short | Description | +| ------------- | ----- | --------------------------------------------------------------- | +| `--id` | | Only report duplicates of the given station (repeatable) | +| `--country` | `-c` | Only check stations in the given country | +| `--radius` | `-r` | Maximum distance in meters for location matches (default: 1000) | +| `--format` | `-f` | Output format: `csv`, `json`, `xlsx`, `parquet` | +| `--output` | `-o` | Output file path (defaults to stdout) | +| `--no-header` | | Omit CSV header row | +| `--all` | `-A` | Print full table without truncation | +| `--repo` | | Path to the stations repository (overrides `stations_repo`) | + +The command exits with code `1` if potential duplicates were found. diff --git a/docs/cli/stations/contributing/edit.md b/docs/cli/stations/contributing/edit.md new file mode 100644 index 0000000..04b8ccf --- /dev/null +++ b/docs/cli/stations/contributing/edit.md @@ -0,0 +1,45 @@ +--- +title: Edit Station | Meteostat CLI +sidebar_label: Edit Station +sidebar_position: 3 +--- + +# Edit Station + +Edit an existing weather station in your [local repository](/cli/stations/contributing#repository-path). + +## Usage + +```bash +meteo station edit ID [OPTIONS] +``` + +Without options, the station's JSON file is opened in your default editor (`$VISUAL` or `$EDITOR`). Once you save and close the file, the station is [validated](validate.md). If validation fails, you can re-open the editor or discard your changes. + +To change individual properties without an editor, use `--set` and `--unset` with dot notation. + +## Examples + +```bash +meteo station edit 10637 # Open in editor +meteo station edit 10637 --set name.en="Frankfurt Airport" # Update a single property +meteo station edit 10637 --set identifiers.icao=EDDF \ + --set location.elevation=111 # Update multiple properties +meteo station edit 10637 --unset identifiers.iata # Remove a property +``` + +## Options + +| Option | Short | Description | +| ----------- | ----- | --------------------------------------------------------------- | +| `--set` | `-s` | Set a property using `KEY=VALUE` with dot notation (repeatable) | +| `--unset` | `-u` | Remove an optional property (repeatable) | +| `--editor` | | Editor command to use instead of `$VISUAL`/`$EDITOR` | +| `--dry-run` | | Print the resulting JSON without writing the file | +| `--repo` | | Path to the stations repository (overrides `stations_repo`) | + +:::info + +The Meteostat ID (`id`) cannot be changed, since it is used to reference the station across all Meteostat products. + +::: diff --git a/docs/cli/stations/contributing/overview.md b/docs/cli/stations/contributing/overview.md new file mode 100644 index 0000000..5114947 --- /dev/null +++ b/docs/cli/stations/contributing/overview.md @@ -0,0 +1,98 @@ +--- +title: Contributing | Meteostat CLI +sidebar_label: Overview +id: cli-contributing-overview +slug: /cli/stations/contributing +sidebar_position: 1 +--- + +import DocCardList from '@theme/DocCardList'; + +# Contributing + +Meteostat maintains an [open directory of weather stations](/data/weather-stations) on [GitHub](https://github.com/meteostat/weather-stations). The Meteostat CLI ships a set of contributor commands which help you add, edit and check station records in a local copy of this repository before you submit a pull request. + +All contributor commands live directly under `meteo station`: + +```text +meteo station +├── add +├── edit +├── delete +├── validate [...] +├── duplicates +└── build +``` + +:::info + +These commands only modify files in your local clone of the stations repository. Nothing is published until your changes are merged into the `main` branch of [meteostat/weather-stations](https://github.com/meteostat/weather-stations). + +::: + +## 📂 Setup {#setup} + +First, fork the [weather stations repository](https://github.com/meteostat/weather-stations) on GitHub and clone your fork: + +```bash +git clone https://github.com//weather-stations.git +``` + +The repository contains one JSON file per weather station in the `stations` directory. Each file is named after the station's Meteostat ID (e.g. `stations/10637.json`). + +### Repository Path {#repository-path} + +The contributor commands need to know where your local clone is located. Set the path once using the `stations_repo` configuration key: + +```bash +meteo config stations_repo ~/code/weather-stations +``` + +The path must point to the root of the repository, i.e. the directory which contains the `stations` folder. You can check the current value at any time: + +```bash +meteo config stations_repo +``` + +To use a different clone for a single command, pass the `--repo` option. It takes precedence over the configured path: + +```bash +meteo station validate --repo ./weather-stations +``` + +If neither `--repo` nor `stations_repo` is set, the CLI uses the current working directory if it looks like a stations repository and exits with an error otherwise. + +## 🔄 Workflow {#workflow} + +A typical contribution looks like this: + +```bash +# 1. Create a branch in your local clone +git -C ~/code/weather-stations checkout -b add-my-station + +# 2. Add or edit station records +meteo station add +meteo station edit 10637 + +# 3. Check your changes +meteo station validate +meteo station duplicates + +# 4. Commit, push and open a pull request +git -C ~/code/weather-stations commit -am "Add my station" +git -C ~/code/weather-stations push -u origin add-my-station +``` + +Please make sure `meteo station validate` passes before opening a pull request. The same checks are run automatically on every pull request. + +## ✍️ Guidelines {#guidelines} + +- Names of weather stations are capitalized. +- Use short and descriptive names for a weather station. +- Refer to aerodromes which handle air cargo or passengers as _airports_ and use the term _airfield_ if they don't. +- Only include identifiers which are actually set. Don't add empty values. +- Prefer [`edit`](edit.md) over [`delete`](delete.md) + [`add`](add.md) so the Meteostat ID of a station stays stable. + +## 👀 Learn More + + diff --git a/docs/cli/stations/contributing/validate.md b/docs/cli/stations/contributing/validate.md new file mode 100644 index 0000000..c32df86 --- /dev/null +++ b/docs/cli/stations/contributing/validate.md @@ -0,0 +1,59 @@ +--- +title: Validate Stations | Meteostat CLI +sidebar_label: Validate Stations +sidebar_position: 5 +--- + +# Validate Stations + +Check station records in your [local repository](/cli/stations/contributing#repository-path) for errors. Validate selected stations by passing their IDs, or all stations when no IDs are given. + +## Usage + +```bash +meteo station validate [ID...] [OPTIONS] +``` + +## Examples + +```bash +meteo station validate # Validate all stations +meteo station validate 10637 # Validate one station +meteo station validate 10637 10638 10639 # Validate several stations +meteo station validate --changed # Validate stations changed on your branch +``` + +## Checks + +Each station is checked for the following: + +- The file contains valid JSON and follows the [schema](https://raw.githubusercontent.com/meteostat/weather-stations/refs/heads/main/schema.json) +- The `id` matches the file name and is a valid Meteostat ID +- `country` is a valid ISO 3166-1 alpha-2 code and `region` a valid ISO 3166-2 subdivision of that country +- `latitude` is between -90 and 90, `longitude` between -180 and 180 and `elevation` is an integer +- `timezone` is a valid IANA time zone +- No other station uses any of the same identifiers (e.g. WMO or ICAO codes) +- Correct formatting (such as capitalized names, ordered identifiers) + +## Output + +Problems are listed per station. The command exits with code `0` if all stations are valid and `1` if at least one error was found, so it can be used in scripts and CI pipelines: + +```text +$ meteo station validate 0A1B2 10637 +✗ 0A1B2 location.latitude: 95.2 is out of range (-90 to 90) +✗ 0A1B2 timezone: "Europa/Frankfurt" is not a valid IANA time zone +✗ 0A1B2 name.en: "frankfurt downtown" should be capitalized +✓ 10637 + +1 of 2 stations invalid (3 errors) +``` + +## Options + +| Option | Short | Description | +| ----------- | ----- | ------------------------------------------------------------------------- | +| `--changed` | | Only validate stations changed compared to `main` (requires Git) | +| `--fix` | | Automatically fix issues where possible (e.g. formatting, mismatched IDs) | +| `--quiet` | `-q` | Only print stations with errors or warnings | +| `--repo` | | Path to the stations repository (overrides `stations_repo`) | diff --git a/docs/cli/stations/overview.md b/docs/cli/stations/overview.md index 6522b5d..fcd88d6 100644 --- a/docs/cli/stations/overview.md +++ b/docs/cli/stations/overview.md @@ -44,6 +44,8 @@ Check what data is available for a station: meteo inventory 10637 ``` +Want to improve the station directory? Check out the [contributor commands](/cli/stations/contributing). + ## 👀 Learn More