From 0ff490111f640fb1f3efa83fc3469acaa54a9073 Mon Sep 17 00:00:00 2001 From: Simon Liu Date: Thu, 2 Apr 2026 16:07:28 -0700 Subject: [PATCH 1/5] update docs build --- .github/workflows/deploy-pages.yml | 23 +++++---- .gitignore | 1 + docs/_config.yml | 1 + docs/intro.md | 3 +- docs/myst.yml | 47 +++++++++++++++++ scripts/update_docs_version.py | 81 ++++++++++++++++++++++++++++++ 6 files changed, 146 insertions(+), 10 deletions(-) create mode 100644 docs/myst.yml create mode 100644 scripts/update_docs_version.py diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 1f08a47f..8f0a8392 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -33,37 +33,42 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - - uses: getsentry/action-github-app-token@v4.0.0 - name: podaac cicd token - id: podaac-cicd - with: - app_id: ${{ secrets.CICD_APP_ID }} - private_key: ${{ secrets.CICD_APP_PRIVATE_KEY }} - uses: actions/checkout@v6 with: repository: ${{ github.repository }} - token: ${{ steps.podaac-cicd.outputs.token }} + - uses: actions/setup-python@v6 with: python-version: ${{ env.PYTHON_VERSION }} + + - uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Sync docs version + run: python scripts/update_docs_version.py + - name: Install Poetry uses: abatilo/actions-poetry@v4 with: poetry-version: ${{ env.POETRY_VERSION }} - # Build the book - name: Build the book + env: + BASE_URL: /hydrocron run: | poetry install --only docs - poetry run jupyter-book build docs/ + NPM_CONFIG_CACHE=/tmp/npm-cache poetry -P . -C docs run jupyter-book build --html - name: Setup Pages uses: actions/configure-pages@v5 + - name: Upload artifact uses: actions/upload-pages-artifact@v4 with: # Upload only docs repository path: 'docs/_build/html' + - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 0bb57be0..d48dfc82 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/_generated_version.md # PyBuilder .pybuilder/ diff --git a/docs/_config.yml b/docs/_config.yml index dc613f6b..30e578c7 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -28,6 +28,7 @@ repository: # Add GitHub buttons to your book # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository html: + baseurl: /hydrocron favicon: hydrocron_logo.png use_issues_button: true use_repository_button: true diff --git a/docs/intro.md b/docs/intro.md index bb2d476b..8e4ae3e9 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,6 +1,7 @@ # Hydrocron Documentation -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11176233.svg)](https://doi.org/10.5281/zenodo.11176233) +Hydrocron version badge +DOI badge Hydrocron is an API that repackages hydrology datasets from the Surface Water and Ocean Topography (SWOT) satellite into formats that make time-series analysis easier. diff --git a/docs/myst.yml b/docs/myst.yml new file mode 100644 index 00000000..9e539baa --- /dev/null +++ b/docs/myst.yml @@ -0,0 +1,47 @@ +version: 1 +project: + title: Hydrocron + copyright: '2024' + github: podaac/hydrocron + edit_url: null + bibliography: + - references.bib + exports: + - format: pdf + template: plain_latex_book + output: exports/book.pdf + toc: + - file: intro.md + - title: GETTING STARTED + children: + - file: overview.md + - file: user-guide/start.md + children: + - file: user-guide/fields.md + - file: user-guide/time.md + - file: user-guide/versioning.md + - file: examples.md + - file: hydrocron_tutorial.ipynb + - title: API ENDPOINTS + children: + - file: timeseries.md + - title: RESOURCES + children: + - url: https://github.com/podaac/hydrocron + title: GitHub Repository + - url: https://podaac.jpl.nasa.gov/SWOT + title: SWOT Mission Page + - url: https://www.swordexplorer.com/ + title: SWOT River Database (SWORD) Explorer + - url: https://podaac.jpl.nasa.gov + title: PO.DAAC Website + - url: https://podaac.github.io/tutorials/ + title: PO.DAAC Cookbook +site: + options: + logo: hydrocron_logo.png + favicon: hydrocron_logo.png + folders: true + template: book-theme + parts: + primary_sidebar_footer: empty-footer.md \ No newline at end of file diff --git a/scripts/update_docs_version.py b/scripts/update_docs_version.py new file mode 100644 index 00000000..4d84fc4f --- /dev/null +++ b/scripts/update_docs_version.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +from pathlib import Path +import tomllib + + +ROOT = Path(__file__).resolve().parents[1] +PYPROJECT = ROOT / "pyproject.toml" +GENERATED_MD = ROOT / "docs" / "_generated_version.md" +GENERATED_SVG = ROOT / "docs" / "_generated_version.svg" + + +def read_version() -> str: + data = tomllib.loads(PYPROJECT.read_text(encoding="utf-8")) + return data["tool"]["poetry"]["version"] + + +def build_badge_svg(version: str) -> str: + label = "Version" + label_width = 60 + value_width = max(60, 20 + len(version) * 7) + total_width = label_width + value_width + height = 20 + + return f""" + + + + + + + + + + + + + + + + {label} + {version} + + +""" + + +def write_generated(version: str) -> bool: + md_content = "![Hydrocron version](_generated_version.svg)\n" + svg_content = build_badge_svg(version) + + md_changed = True + if GENERATED_MD.exists(): + current_md = GENERATED_MD.read_text(encoding="utf-8") + md_changed = current_md != md_content + + svg_changed = True + if GENERATED_SVG.exists(): + current_svg = GENERATED_SVG.read_text(encoding="utf-8") + svg_changed = current_svg != svg_content + + if md_changed: + GENERATED_MD.write_text(md_content, encoding="utf-8") + if svg_changed: + GENERATED_SVG.write_text(svg_content, encoding="utf-8") + + return md_changed or svg_changed + + +def main() -> None: + version = read_version() + changed = write_generated(version) + if changed: + print(f"Updated docs/_generated_version.* to version {version}") + else: + print(f"docs/_generated_version.* already at version {version}") + + +if __name__ == "__main__": + main() From 74454765b21d240a84ed87e4ce6a1f0139ed3b25 Mon Sep 17 00:00:00 2001 From: Simon Liu Date: Thu, 2 Apr 2026 16:08:58 -0700 Subject: [PATCH 2/5] only build pages on main --- .github/workflows/deploy-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 8f0a8392..1f5e6a4d 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -4,7 +4,7 @@ name: Deploy documentation to Pages on: # Runs on pushes targeting the default branch push: - branches: ["develop"] + branches: ["main"] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: From d1a8b8be62b250efcfd12e5caf6c1ca2b5021119 Mon Sep 17 00:00:00 2001 From: Simon Liu Date: Thu, 2 Apr 2026 16:36:46 -0700 Subject: [PATCH 3/5] add footer --- docs/footer.md | 4 ++++ docs/myst.yml | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 docs/footer.md diff --git a/docs/footer.md b/docs/footer.md new file mode 100644 index 00000000..27264a33 --- /dev/null +++ b/docs/footer.md @@ -0,0 +1,4 @@ +
+ By Physical Oceanography Distributed Active Archive Center (PO.DAAC)
+ © Copyright 2024. +
diff --git a/docs/myst.yml b/docs/myst.yml index 9e539baa..506e529c 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -44,4 +44,5 @@ site: folders: true template: book-theme parts: - primary_sidebar_footer: empty-footer.md \ No newline at end of file + primary_sidebar_footer: empty-footer.md + footer: footer.md \ No newline at end of file From 662ec35ec7ef8f87e4e666ea515394a1deb37772 Mon Sep 17 00:00:00 2001 From: Simon Liu Date: Thu, 2 Apr 2026 20:11:36 -0700 Subject: [PATCH 4/5] update docs versioning --- scripts/update_docs_version.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/scripts/update_docs_version.py b/scripts/update_docs_version.py index 4d84fc4f..48642db1 100644 --- a/scripts/update_docs_version.py +++ b/scripts/update_docs_version.py @@ -2,6 +2,7 @@ from __future__ import annotations from pathlib import Path +import re import tomllib @@ -9,6 +10,7 @@ PYPROJECT = ROOT / "pyproject.toml" GENERATED_MD = ROOT / "docs" / "_generated_version.md" GENERATED_SVG = ROOT / "docs" / "_generated_version.svg" +PRE_RELEASE_PATTERN = re.compile(r"^(\d+(?:\.\d+)*)(?:a|b|rc)\d+.*$") def read_version() -> str: @@ -16,6 +18,13 @@ def read_version() -> str: return data["tool"]["poetry"]["version"] +def normalize_release_version(version: str) -> str: + match = PRE_RELEASE_PATTERN.match(version) + if match: + return match.group(1) + return version + + def build_badge_svg(version: str) -> str: label = "Version" label_width = 60 @@ -69,7 +78,7 @@ def write_generated(version: str) -> bool: def main() -> None: - version = read_version() + version = normalize_release_version(read_version()) changed = write_generated(version) if changed: print(f"Updated docs/_generated_version.* to version {version}") From dcb45af79c19d59144147f7f5bdb28453aa6d448 Mon Sep 17 00:00:00 2001 From: Simon Liu Date: Tue, 7 Apr 2026 10:16:33 -0700 Subject: [PATCH 5/5] update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 50160f59..100930b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added ### Changed + - Issue 329 - Fix docs so they deploy when we make a new release ### Deprecated ### Removed ### Fixed