Skip to content

Commit 8c44c15

Browse files
abarciauskas-bgseabarciauskas-bgse
authored
Merge pull request #109 from developmentseed/feat/reorg-documentation
Feat/reorg documentation
2 parents 5a5fb05 + a6d1caf commit 8c44c15

26 files changed

+6618
-1612
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ on:
88
workflow_dispatch:
99
inputs:
1010
version:
11-
description: 'Version to deploy (e.g., 0.1.4, or "dev" for develop branch)'
11+
description: 'Version to deploy (e.g., 0.1.4, "dev" for develop branch, or branch name like "feat/reorg-documentation")'
1212
required: true
1313
type: string
1414

@@ -27,7 +27,7 @@ jobs:
2727
- uses: actions/checkout@v4
2828
with:
2929
fetch-depth: 0 # Important for mike to work with tags
30-
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.version != 'dev' && format('v{0}', inputs.version) || github.ref }}
30+
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.version != 'dev' && (startsWith(inputs.version, 'v') || contains(inputs.version, '/')) && inputs.version || github.event_name == 'workflow_dispatch' && inputs.version != 'dev' && format('v{0}', inputs.version) || github.ref }}
3131

3232
- uses: astral-sh/setup-uv@v7
3333
with:
@@ -36,6 +36,7 @@ jobs:
3636
- name: Sync
3737
run: |
3838
uv sync
39+
uv pip install -e docs/packages/datacube_benchmark
3940
git restore uv.lock
4041
4142
- name: Configure Git
@@ -60,7 +61,14 @@ jobs:
6061
if [[ "$VERSION" == "dev" ]]; then
6162
uv run mike deploy --push --update-aliases dev
6263
uv run mike set-default --push dev
64+
elif [[ "$VERSION" == *"/"* ]]; then
65+
# Branch name detected (contains /)
66+
# Sanitize branch name for use as mike version (replace / with -)
67+
SAFE_VERSION=$(echo "$VERSION" | sed 's/\//-/g')
68+
echo "Deploying branch version: $SAFE_VERSION"
69+
uv run mike deploy --push $SAFE_VERSION
6370
else
71+
# Assume it's a version number
6472
uv run mike deploy --push $VERSION
6573
6674
# Check if this should be the latest version

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,21 @@ To preview the documentation in your browser you can run:
5555
```bash
5656
uv run mkdocs serve -o
5757
```
58+
59+
### Previewing documentation changes
60+
61+
To preview documentation changes on a specific branch, you can deploy a specific branch to the documentation site using Github Actions workflow dispatch. This will create a new "version" of the documentation which is discoverable in the documentation drop down:
62+
63+
<img alt="Docs Dropdown" src="./docs/assets/docs-dropdown.png" style="width: 350px"/>
64+
65+
This "version" of the documentation is really just a new directory of the documentation in the gh-pages branch of this repository.
66+
67+
Remember to delete that branch when you are done:
68+
69+
```
70+
uv run mike delete feat-reorg-documentation --push
71+
```
72+
73+
This will:
74+
1. Delete the feat-reorg-documentation version from the documentation
75+
2. Push the changes to the gh-pages branch

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616

1717
An API for creating image tiles from CMR queries.
1818

19+
See also the [API documentation](https://staging.openveda.cloud/api/titiler-cmr/api.html).
20+
1921
## Features
2022

2123
- Render tiles from assets discovered via queries to [NASA's CMR](https://cmr.earthdata.nasa.gov/search)

‎docs/api/compatibility_api_example.ipynb‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "cdeef4c6-75b0-44d9-90d4-c850b5d8908a",
6+
"metadata": {},
7+
"source": [
8+
"# How to use the Compatibility API\n",
9+
"\n",
10+
"The `/compatibility` endpoint displays information about the collection and returns some details about a sample granule. The output is helpful for understanding the structure of the collection and the granules so that you can craft the right set of parameters for visualization or statistics requests.\n",
11+
"\n",
12+
"This notebook demonstrates how to use the compatibility endpoint for th [GHRSST Level 4 MUR Global Foundation Sea Surface Temperature Analysis (v4.1)](https://cmr.earthdata.nasa.gov/search/concepts/C1996881146-POCLOUD) dataset.\n",
13+
"\n",
14+
"## Setup"
15+
]
16+
},
17+
{
18+
"cell_type": "code",
19+
"execution_count": null,
20+
"id": "7d015182-5347-437a-8b66-d7d62212f0e3",
21+
"metadata": {},
22+
"outputs": [],
23+
"source": [
24+
"import json\n",
25+
"import earthaccess\n",
26+
"import httpx\n",
27+
"\n",
28+
"titiler_endpoint = \"https://staging.openveda.cloud/api/titiler-cmr\" # staging endpoint"
29+
]
30+
},
31+
{
32+
"cell_type": "markdown",
33+
"id": "d375b5b7-9322-4f1e-8859-000ef8ac4898",
34+
"metadata": {},
35+
"source": [
36+
"## Identify the dataset\n",
37+
"\n",
38+
"You can find the MUR SST dataset using the `earthaccess.search_datasets` function."
39+
]
40+
},
41+
{
42+
"cell_type": "code",
43+
"execution_count": null,
44+
"id": "f3fcc9cd-6105-42fc-98bf-2de40910a79c",
45+
"metadata": {},
46+
"outputs": [],
47+
"source": [
48+
"datasets = earthaccess.search_datasets(doi=\"10.5067/GHGMR-4FJ04\")\n",
49+
"ds = datasets[0]\n",
50+
"\n",
51+
"concept_id = ds[\"meta\"][\"concept-id\"]\n",
52+
"print(\"Concept-Id: \", concept_id)\n",
53+
"\n",
54+
"print(\"Abstract: \", ds[\"umm\"][\"Abstract\"])"
55+
]
56+
},
57+
{
58+
"cell_type": "markdown",
59+
"id": "2a4cffa6-0059-4033-a708-db60d743f0e3",
60+
"metadata": {},
61+
"source": [
62+
"## Explore the collection using the `/compatibility` endpoint"
63+
]
64+
},
65+
{
66+
"cell_type": "code",
67+
"execution_count": null,
68+
"id": "1bde609a-26df-4f35-b7e1-9e1922e87808",
69+
"metadata": {},
70+
"outputs": [],
71+
"source": [
72+
"compatibility_response = httpx.get(\n",
73+
" f\"{titiler_endpoint}/compatibility\",\n",
74+
" params={\"concept_id\": concept_id},\n",
75+
" timeout=None,\n",
76+
").json()\n",
77+
"\n",
78+
"print(json.dumps(compatibility_response, indent=2))"
79+
]
80+
},
81+
{
82+
"cell_type": "markdown",
83+
"id": "04014a32-9c11-4b75-b40a-e5ad4efd686b",
84+
"metadata": {},
85+
"source": [
86+
"The details from the sample granule show that it is a NetCDF file with four variables (`analysed_sst`, `analysis_error`, `mask`, and `sea_ice_fraction`) and each contains an array with a single time coordinate. The `datetime` key shows the reported temporal range from CMR which indicates that the dataset has granules from `2002-05-31` to present. For each variable several summary statistics are available to help you craft min/max values for the `rescale` parameter.\n",
87+
"\n",
88+
"This information is handy for generating tiles via the tiles API, which you can learn more about in [the Tiles API Documentation](../tiling_api_xarray_backend_example)."
89+
]
90+
},
91+
{
92+
"cell_type": "markdown",
93+
"id": "05f8766c",
94+
"metadata": {},
95+
"source": []
96+
}
97+
],
98+
"metadata": {
99+
"kernelspec": {
100+
"display_name": "Python 3 (ipykernel)",
101+
"language": "python",
102+
"name": "python3"
103+
},
104+
"language_info": {
105+
"codemirror_mode": {
106+
"name": "ipython",
107+
"version": 3
108+
},
109+
"file_extension": ".py",
110+
"mimetype": "text/x-python",
111+
"name": "python",
112+
"nbconvert_exporter": "python",
113+
"pygments_lexer": "ipython3",
114+
"version": "3.12.3"
115+
}
116+
},
117+
"nbformat": 4,
118+
"nbformat_minor": 5
119+
}

docs/examples/rasterio_backend_example.ipynb renamed to docs/api/rasterio_backend_example.ipynb

Lines changed: 8 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,13 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"# rasterio backend example: HLS\n",
8-
"This notebook demonstrates how to use titiler-cmr's `rasterio` backend to render tiles for collections with granules that contain two-dimensional raster data.\n",
7+
"# How to use the API with the Rasterio Backend\n",
98
"\n",
10-
"In addition to showing how to parameterize `tilesson` endpoint requests this guide also demonstrates how to use the [`earthaccess`](https://earthaccess.readthedocs.io/en/latest/) package to search for collections and how the relevant details for tiling can be extracted from the search results.\n",
9+
"Since most of the API documentation uses the `xarray` backend, this notebook provides an example of how to use most endpoints with the `rasterio` backend.\n",
1110
"\n",
12-
"#### Requirements\n",
13-
"To run some of the chunks in this notebook you will need to install a few packages:\n",
11+
"See also the [API docs](https://staging.openveda.cloud/api/titiler-cmr/api.html).\n",
1412
"\n",
15-
"- `earthaccess`\n",
16-
"- `folium`\n",
17-
"- `httpx`\n",
18-
"\n",
19-
"`!pip install folium httpx earthaccess`"
13+
"## Setup"
2014
]
2115
},
2216
{
@@ -32,21 +26,10 @@
3226
"import earthaccess\n",
3327
"import httpx\n",
3428
"\n",
35-
"from folium import Map, TileLayer"
36-
]
37-
},
38-
{
39-
"cell_type": "code",
40-
"execution_count": null,
41-
"metadata": {},
42-
"outputs": [],
43-
"source": [
44-
"# titiler_endpoint = \"http://localhost:8081\" # docker network endpoint\n",
45-
"# titiler_endpoint = (\n",
46-
"# \"https://staging.openveda.cloud/api/titiler-cmr\" # VEDA staging endpoint\n",
47-
"# )\n",
29+
"from folium import Map, TileLayer\n",
30+
"\n",
4831
"titiler_endpoint = (\n",
49-
" \"https://v4jec6i5c0.execute-api.us-west-2.amazonaws.com\" # dev endpoint\n",
32+
" \"https://staging.openveda.cloud/api/titiler-cmr\" # VEDA staging endpoint\n",
5033
")"
5134
]
5235
},
@@ -77,9 +60,7 @@
7760
"cell_type": "markdown",
7861
"metadata": {},
7962
"source": [
80-
"## Explore the collection using the `/compatibility` endpoint\n",
81-
"\n",
82-
"The `/compatibility` endpoint will display information about the collection and return some details about a sample granule. The output is helpful for understanding the structure of the collection and the granules so that you can craft the right set of parameters for visualization or statistics requests."
63+
"## Explore the collection using the `/compatibility` endpoint"
8364
]
8465
},
8566
{
@@ -113,35 +94,6 @@
11394
"While rendering `xyz` tile images, `titiler-cmr` searches for assets using the `assets_for_tile` method which converts the `xyz` tile extent into a bounding box."
11495
]
11596
},
116-
{
117-
"cell_type": "code",
118-
"execution_count": null,
119-
"metadata": {},
120-
"outputs": [],
121-
"source": [
122-
"from titiler.cmr.backend import CMRBackend\n",
123-
"from titiler.cmr.reader import MultiFilesBandsReader\n",
124-
"\n",
125-
"with CMRBackend(reader=MultiFilesBandsReader) as backend:\n",
126-
" assets = backend.assets_for_tile(\n",
127-
" x=62,\n",
128-
" y=44,\n",
129-
" z=7,\n",
130-
" bands_regex=\"B[0-9][0-9]\",\n",
131-
" concept_id=concept_id,\n",
132-
" temporal=(\"2024-02-11\", \"2024-02-13\"),\n",
133-
" )\n",
134-
"\n",
135-
"print(json.dumps(assets[0], indent=2))"
136-
]
137-
},
138-
{
139-
"cell_type": "markdown",
140-
"metadata": {},
141-
"source": [
142-
"## `titiler.cmr` API documentation"
143-
]
144-
},
14597
{
14698
"cell_type": "code",
14799
"execution_count": null,

0 commit comments

Comments
 (0)