Get docs working and update example

.github/workflows/Documentation.yml

@@ -0,0 +1,80 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+
+      - uses: julia-actions/cache@v2
+
+      - name: Install dependencies
+        run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+
+      - name: Build documentation
+        run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-build
+          path: docs/build/
+          retention-days: 7
+
+  deploy-docs:
+    name: Deploy
+    needs: build-docs
+    runs-on: ubuntu-latest
+    # Deploy on pushes to main or tags, and PRs from the same repo (not forks)
+    if: github.event_name == 'push' || (github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork)
+    permissions:
+      contents: write
+      pull-requests: read
+      statuses: write
+    concurrency:
+      group: docs-deploy
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: documentation-build
+          path: docs/build/
+
+      - name: Install Documenter
+        run: julia -e 'using Pkg; Pkg.add("Documenter")'
+
+      - name: Deploy documentation
+        run: julia docs/deploy.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -15,3 +15,11 @@ Manifest.toml
 
 *.png
 *.mp4
+*.js
+*.html
+*.css
+
+docs/build/
+docs/literated/
+
+

README.md

@@ -1,98 +1,100 @@
-# CopernicusClimateDataStore.jl
+<!-- Title -->
+<h1 align="center">
+  CopernicusClimateDataStore.jl
+</h1>
 
-Julia wrapper around the [Copernicus Climate Data Store (CDS)](https://cds.climate.copernicus.eu/)
-for downloading ERA5 reanalysis data.
+<!-- description -->
+<p align="center">
+  <strong>🌍 Julia interface to the <a href="https://cds.climate.copernicus.eu/">Copernicus Climate Data Store</a> for downloading ERA5 reanalysis data</strong>
+</p>
 
-## Installation
+<p align="center">
+  <a href="https://numericalearth.github.io/CopernicusClimateDataStore.jl/dev/">
+    <img alt="Documentation" src="https://img.shields.io/badge/documentation-in%20development-orange?style=flat-square">
+  </a>
+</p>
+
+CopernicusClimateDataStore.jl wraps the [`era5cli`](https://era5cli.readthedocs.io/) command-line tool,
+providing a convenient Julia interface for downloading ERA5 hourly and monthly data to NetCDF or GRIB.
+
+### Installation
 
 ```julia
 using Pkg
-Pkg.add(url="https://github.com/YOUR_USERNAME/CopernicusClimateDataStore.jl")
+Pkg.add(url="https://github.com/NumericalEarth/CopernicusClimateDataStore.jl")
 ```
 
-## CDS Account Setup
+### Before you start
 
-Before downloading data, you must:
+You need a Copernicus Climate Data Store account:
 
-1. **Create a CDS account** at https://cds.climate.copernicus.eu/
-2. **Accept the Terms of Use** for the ERA5 dataset at
-   https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels?tab=download#manage-licences
-3. **Configure your API key** by running:
+1. **Create an account** at https://cds.climate.copernicus.eu/
+2. **Accept the ERA5 Terms of Use** at https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels
+3. **Configure your API key**:
    ```bash
    era5cli config --key YOUR_PERSONAL_ACCESS_TOKEN
    ```
 
-Your personal access token can be found on your CDS profile page after logging in.
+Your personal access token is on your [CDS profile page](https://cds.climate.copernicus.eu/).
 
-## Quick Start
+### Quick start
+
+Download and visualize 2-metre temperature over Europe:
 
 ```julia
 using CopernicusClimateDataStore
 using NCDatasets
 using CairoMakie
 
-# Download 2m temperature for Europe, Jan 1, 2020 at 12:00 UTC
-files = hourly(
-    variables = "2m_temperature",
-    startyear = 2020,
-    months = 1,
-    days = 1,
-    hours = 12,
-    area = (lat = (35, 60), lon = (-10, 25)),
-    format = "netcdf",
-    outputprefix = "europe"
-)
-
-# Load the downloaded file
-filename = first(files)
-ds = NCDataset(filename)
-
-lon = ds["longitude"][:]
-lat = ds["latitude"][:]
-temp_C = ds["t2m"][:, :, 1] .- 273.15
+files = hourly(variables = "2m_temperature",
+               startyear = 2020,
+               months = 6,
+               days = 21,
+               hours = 12,
+               area = (lat = (35, 70), lon = (-15, 40)),
+               outputprefix = "europe")
+
+# Load the data
+ds = NCDataset(first(files))
+λ = ds["longitude"][:]         # degrees East
+φ = ds["latitude"][:]          # degrees North
+T = ds["t2m"][:, :, 1] .- 273.15  # K → °C
 close(ds)
 
 # Plot
-fig = Figure(size = (800, 600))
-ax = Axis(fig[1, 1], xlabel = "Longitude", ylabel = "Latitude")
-hm = heatmap!(ax, lon, lat, temp_C', colormap = :thermal)
-Colorbar(fig[1, 2], hm, label = "Temperature (°C)")
+fig, ax, hm = heatmap(λ, φ, T'; colormap = :thermal)
+Colorbar(fig[1, 2], hm; label = "Temperature (°C)")
+ax.xlabel = "λ (°E)"
+ax.ylabel = "φ (°N)"
 save("temperature.png", fig)
 ```
 
-## API
-
-### `hourly(; variables, startyear, ...)`
+![](temperature.png)
 
-Download ERA5 hourly data.
+### Key arguments
 
-**Key arguments:**
-- `variables`: Variable name(s), e.g. `"2m_temperature"`
-- `startyear`, `endyear`: Year range
-- `months`, `days`, `hours`: Time filters
-- `area`: Bounding box `(lat = (south, north), lon = (west, east))`
-- `format`: `"netcdf"` (default) or `"grib"`
-- `outputprefix`: Prefix for output filename
-- `dryrun`: If `true`, print command without downloading
-- `splitmonths`: Split output by month (default: `true`)
-- `merge`: Merge all output into a single file (default: `false`)
+| Argument | Description |
+|:---------|:------------|
+| `variables` | Variable name, e.g. `"2m_temperature"`, `"total_precipitation"` |
+| `startyear` | Year to download (required) |
+| `months` | Month or months (1–12) |
+| `days` | Day or days (1–31) |
+| `hours` | Hour or hours (0–23) |
+| `area` | Bounding box: `(lat = (south, north), lon = (west, east))` |
+| `format` | `"netcdf"` (default) or `"grib"` |
+| `outputprefix` | Prefix for output filename |
+| `merge` | Merge all data into a single file (default: `false`) |
 
-**Note:** By default, one file is created per month. Use `merge=true` for a single file.
+By default, one file is created per month. Use `merge = true` for a single file.
 
 ### Common variables
 
 | Request name | NetCDF name | Description |
-|-------------|-------------|-------------|
-| `2m_temperature` | `t2m` | 2 metre temperature (K) |
-| `10m_u_component_of_wind` | `u10` | 10 metre U wind (m/s) |
-| `10m_v_component_of_wind` | `v10` | 10 metre V wind (m/s) |
+|:-------------|:------------|:------------|
+| `2m_temperature` | `t2m` | 2-metre temperature (K) |
+| `10m_u_component_of_wind` | `u10` | 10-metre zonal wind (m/s) |
+| `10m_v_component_of_wind` | `v10` | 10-metre meridional wind (m/s) |
 | `total_precipitation` | `tp` | Total precipitation (m) |
+| `mean_sea_level_pressure` | `msl` | Mean sea level pressure (Pa) |
 
-## Examples
-
-See the `examples/` directory for Literate-style examples including an animation
-of European temperature evolution.
-
-## License
-
-Apache License 2.0
+See the [CDS ERA5 documentation](https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels) for a complete list.

docs/Project.toml

@@ -5,6 +5,9 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 
+[sources]
+CopernicusClimateDataStore = {path = ".."}
+
 [compat]
 CairoMakie = "0.12, 0.13"
 Documenter = "1"

docs/deploy.jl

@@ -0,0 +1,20 @@
+using Documenter
+
+@info "Cleaning up temporary .jld2 and .nc output created by doctests or literated examples..."
+
+for (root, _, filenames) in walkdir(@__DIR__)
+    for file in filenames
+        if any(occursin(file), (r"\.jld2$", r"\.nc$", r"\.grib$"))
+            rm(joinpath(root, file); force=true)
+        end
+    end
+end
+
+deploydocs(;
+    repo = "github.com/NumericalEarth/CopernicusClimateDataStore.jl",
+    devbranch = "main",
+    # Only push previews if all the relevant environment variables are non-empty. This is an
+    # attempt to work around https://github.com/JuliaDocs/Documenter.jl/issues/2048.
+    push_preview = all(!isempty, (get(ENV, "GITHUB_TOKEN", ""), get(ENV, "DOCUMENTER_KEY", ""))),
+    forcepush = true,
+)

docs/make.jl

@@ -13,13 +13,15 @@ examples = [
     ("European temperature evolution", "european_temperature_evolution"),
 ]
 
+#=
 for (title, basename) in examples
     script_path = joinpath(examples_src_dir, basename * ".jl")
     @info "Building example: $title"
     run(`$(Base.julia_cmd()) --project=$(dirname(Base.active_project())) $(joinpath(@__DIR__, "literate.jl")) $script_path $literated_dir`)
 end
 
 example_pages = [title => joinpath("literated", basename * ".md") for (title, basename) in examples]
+=#
 
 makedocs(
     sitename = "CopernicusClimateDataStore.jl",
@@ -30,7 +32,9 @@ makedocs(
     ),
     pages = [
         "Home" => "index.md",
-        "Examples" => example_pages,
+        # "Examples" => example_pages,
+        "API Reference" => "api.md",
     ],
 )
 
+

docs/src/api.md

@@ -0,0 +1,24 @@
+# API Reference
+
+## Main Functions
+
+```@docs
+hourly
+info
+```
+
+## Installation and CLI
+
+```@docs
+install_era5cli
+era5cli_cmd
+```
+
+## Internal Functions
+
+```@docs
+CopernicusClimateDataStore.build_hourly_cmd
+CopernicusClimateDataStore.format_area
+CopernicusClimateDataStore.monthly
+```
+

docs/src/index.md

@@ -10,7 +10,7 @@ providing a convenient Julia interface for downloading ERA5 and ERA5-Land data.
 
 ```julia
 using Pkg
-Pkg.add(url="https://github.com/YOUR_USERNAME/CopernicusClimateDataStore.jl")
+Pkg.add(url="https://github.com/NumericalEarth/CopernicusClimateDataStore.jl")
 ```
 
 ## CDS Account Setup

examples/Project.toml

@@ -3,6 +3,9 @@ CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 CopernicusClimateDataStore = "bce3f73f-acea-4481-bd86-df89ecc2cb46"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 
+[sources]
+CopernicusClimateDataStore = {path = ".."}
+
 [compat]
 CairoMakie = "0.12, 0.13"
 NCDatasets = "0.14, 0.15"