Feature/fix docs

.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:
@@ -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

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_generated_version.md
 
 # PyBuilder
 .pybuilder/

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

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

docs/footer.md

@@ -0,0 +1,4 @@
+<div style="text-align: center; font-size: 0.9em; color: #666; padding: 2rem 0;">
+  By Physical Oceanography Distributed Active Archive Center (PO.DAAC)<br>
+  &copy; Copyright 2024.
+</div>

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)
+<a href="#"><img src="_generated_version.svg" alt="Hydrocron version badge" align="left"></a>
+<a href="https://zenodo.org/records/11176233"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.11176233.svg" alt="DOI badge" align="left"></a>
 
 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.
 

docs/myst.yml

@@ -0,0 +1,48 @@
+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
+      footer: footer.md

scripts/update_docs_version.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from pathlib import Path
+import re
+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"
+PRE_RELEASE_PATTERN = re.compile(r"^(\d+(?:\.\d+)*)(?:a|b|rc)\d+.*$")
+
+
+def read_version() -> str:
+    data = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    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
+    value_width = max(60, 20 + len(version) * 7)
+    total_width = label_width + value_width
+    height = 20
+
+    return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{total_width}" height="{height}" role="img" aria-label="{label}: {version}">
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#fff" stop-opacity=".7"/>
+    <stop offset=".1" stop-color="#aaa" stop-opacity=".1"/>
+    <stop offset=".9" stop-color="#000" stop-opacity=".3"/>
+    <stop offset="1" stop-color="#000" stop-opacity=".5"/>
+  </linearGradient>
+  <clipPath id="r">
+    <rect width="{total_width}" height="{height}" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="{label_width}" height="{height}" fill="#555"/>
+    <rect x="{label_width}" width="{value_width}" height="{height}" fill="#007ec6"/>
+    <rect width="{total_width}" height="{height}" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11">
+    <text x="{label_width / 2}" y="14">{label}</text>
+    <text x="{label_width + value_width / 2}" y="14">{version}</text>
+  </g>
+</svg>
+"""
+
+
+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 = normalize_release_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()