diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 1f08a47f..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: @@ -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/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 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/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/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..506e529c --- /dev/null +++ b/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 \ 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..48642db1 --- /dev/null +++ b/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""" + + + + + + + + + + + + + + + + {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 = 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()