Add docstrings step to calkit-run workflow; run Python scripts via uv by Copilot · Pull Request #185 · symbiotic-engineering/MDOcean

Copilot · 2026-04-10T04:30:20Z

dev/docs/add_docstrings.py existed to stamp Sphinx-compatible docstrings onto .m files but was never wired into CI. Additionally, the workflow used actions/setup-python + pip install for two lightweight Python scripts that uv can handle directly.

Changes

New step: Run dev/docs/add_docstrings.py after checkout; any modified .m files are saved alongside pipeline outputs in the calkit save step
Removed actions/setup-python and pip install ruamel.yaml steps — both scripts now run via uv run with Python 3.12 pinned via astral-sh/setup-uv:
- uv run python dev/docs/add_docstrings.py (stdlib-only)
- uv run --with ruamel.yaml python mdocean/analysis/update_calkit.py (ruamel.yaml resolved on-the-fly)
calkit save extended to include *.m files and a fork PR guard (skips save/push for fork PRs)
Fixed incorrect parameter and return names in autogenerated docstring for contourx.m (X→X_data, Y→Y_data, Z→Z_data, water depth (m)→h_fig)
Bumped version to v1.1.21 and added changelog entry

Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/08b57ff7-b66b-4abc-abac-89ada4866851 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/7da3e26b-99ee-4612-a551-42db6102f445 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot

Pull request overview

Updates the Calkit CI workflow to automatically apply MATLAB Sphinx docstring stamping and to run lightweight Python utilities via uv instead of a pre-installed Python + pip setup.

Changes:

Adds a workflow step to run dev/docs/add_docstrings.py and auto-commit/push resulting .m docstring updates.
Replaces direct python execution with uv run (including on-the-fly install of ruamel.yaml) for mdocean/analysis/update_calkit.py.
Removes actions/setup-python and pip install ruamel.yaml steps from the workflow.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-10T05:34:15Z

+      - name: Add docstrings to .m files
+        run: |
+          uv run python dev/docs/add_docstrings.py
+          if git diff --quiet; then


uv run python ... relies on a python executable being available on the self-hosted runner, but this workflow no longer installs/chooses a Python version (it removed actions/setup-python). If the runner image changes or lacks Python, this step will fail and the workflow becomes non-reproducible across runners. Consider explicitly selecting/installing a Python version (e.g., via uv's Python management or re-adding setup-python) so uv run has a guaranteed interpreter.

@copilot apply changes based on this feedback use uv python mgmt

Applied in commit 97d09d6. Added python-version: "3.12" to the astral-sh/setup-uv@v7 step — uv will install and pin Python 3.12 on the runner, guaranteeing a consistent interpreter for both uv run invocations (the docstrings step and update_calkit.py).

Copilot · 2026-04-10T05:34:15Z

+          else
+            git add mdocean/
+            git commit -m "Add autogenerated docstrings to .m files [skip ci]"


git add mdocean/ stages the entire directory, which can accidentally include unrelated modifications (e.g., file permission/line-ending churn on self-hosted runners or other generated artifacts if anything else touched mdocean/). To reduce the risk of committing unintended changes, stage only the expected .m docstring updates (or only tracked changes) rather than the whole tree.

@copilot apply changes based on this feedback

Already addressed in commit 5c10afe. git add mdocean/ was replaced with git add -u -- '*.m', which stages only tracked .m file modifications and ignores any other changes in the directory.

Copilot · 2026-04-10T05:34:15Z

+            git commit -m "Add autogenerated docstrings to .m files [skip ci]"
+            git push
+          fi


This step unconditionally git pushes during a pull_request workflow run. That can fail (and fail the whole job) on non-fast-forward updates if the branch moves while the job is running, and it will not work for fork PRs (no permission / branch not in the base repo). Consider guarding the commit/push so it only runs for same-repo PRs, and add push error handling (e.g., pull/rebase + retry, or fall back to creating a new branch as done later in the workflow).

@copilot apply changes based on this feedback

Applied in commit 5c10afe:

Staging narrowed: changed git add mdocean/ → git add -u -- '*.m' so only tracked .m file changes are staged (not the whole directory tree).

Fork PR guard: the commit/push block now checks github.event.pull_request.head.repo.full_name != github.repository and skips the push for fork PRs.

Push error handling: added git pull --rebase before pushing; if the rebase fails, falls back to creating a new branch (docstrings-<run_number>-<run_id>) and pushing there — mirroring the pattern already used in the calkit save step.

don't duplicate this branching logic, just remove the add/commit/push from this step entirely and add *.m as an input to the calkit save below, and put the if not fork logic in that step.

Applied in commit a0e58dc:

"Add docstrings to .m files" step now just runs uv run python dev/docs/add_docstrings.py — all commit/push logic removed.

'*.m' added to the calkit save file list so docstring changes are committed with the pipeline outputs.

Fork PR guard added at the top of calkit save (skips save/push for fork PRs).

…ull --rebase retry Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/3dd0a364-c68b-4765-9248-f7827c479e19 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

…for uv run steps Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/6d07ea9c-f939-4dc2-bdeb-15e7d5a15c29 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

rebeccamccabe · 2026-04-10T06:54:40Z

+            git commit -m "Add autogenerated docstrings to .m files [skip ci]"
+            git push
+          fi


don't duplicate this branching logic, just remove the add/commit/push from this step entirely and add *.m as an input to the calkit save below, and put the if not fork logic in that step.

…n calkit save Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/040712ef-0a07-426a-bf74-541b9c73bbb8 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

rebeccamccabe · 2026-04-13T01:04:55Z

 function [C,h] = contourx(X,Y,Z,varargin)
+% Function contourx
+%
+% :param X: Design variable vector


incorrect X and h

Fixed in commit d80c641 — updated :param X: → :param X_data:, :param Y: → :param Y_data:, :param Z: → :param Z_data:, and :returns: water depth (m) → :returns: h_fig.

rebeccamccabe · 2026-04-13T01:12:32Z

wecsim errors changing is not expected just due to docstring additions, it must indicate that the wecsim stage on main was stale? maybe if the last-merged PR had a conflict so pushed to a different branch?

rebeccamccabe · 2026-04-15T01:07:45Z

@copilot merge main into this branch and resolve merge conflicts by checking out theirs for all conflicted files. You may have to pull/fetch main first to ensure it is the most updated version. Ensure it is a proper merge commit with two parents, not a regular commit. Then, bump mdocean/version.py and add an entry to the changelog summarizing this PR.

Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

….1.21 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot · 2026-04-15T01:12:35Z

@copilot merge main into this branch and resolve merge conflicts by checking out theirs for all conflicted files. You may have to pull/fetch main first to ensure it is the most updated version. Ensure...

Done in commit 960bdd7:

Merged main (v1.1.20) into this branch as a proper two-parent merge commit; conflicts in data/result files resolved by checking out theirs.
Bumped mdocean/__version__.py to 1.1.21.
Added v1.1.21 entry to CHANGELOG.md summarizing the CI changes in this PR.

rebeccamccabe · 2026-04-15T12:40:16Z

Pipeline completed successfully. Need to resolve merge conflicts using theirs and do a manual dvc commit to enforce that the stages don’t get unnecessarily rerun.

rebeccamccabe · 2026-04-17T05:29:33Z

@copilot add a feature to the Calkit run.yaml github actions workflow where ‘calkit dvc commit stagenames’ followed by “git add dvc.lock *.m” and “git commit-m “Update docstrings and force-commit dvc stages” is run for stage names where they were clean (‘Calkit status stagename’ was not stale) before running the docstring generation, but they are dirty (Calkit status showing as stale) after adding the doc strings. If a given stage was dirty before adding doc strings then it should not be dvc committed.

… newly stale stages Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/2b5f2492-8c47-49ee-9c56-d1c7fd1d6dbf Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot · 2026-04-17T05:32:23Z

@copilot add a feature to the Calkit run.yaml github actions workflow where ‘calkit dvc commit stagenames’ followed by “git add dvc.lock *.m” and “git commit-m “Update docstrings and force...

Applied in commit 4cca5c6. The "Add docstrings to .m files" step now:

Captures which stages are already stale (dvc status --json | jq -r 'keys[]') before running add_docstrings.py
Runs uv run python dev/docs/add_docstrings.py
Captures stale stages after
Computes the set difference — stages that were clean before but stale after (i.e., newly dirtied only by docstrings)
For that set: runs calkit dvc commit <stages>, then git add dvc.lock '*.m' and git commit -m "Update docstrings and force-commit dvc stages" (skipped if the staged diff is empty)

Stages that were already dirty before docstring generation are excluded from the force-commit.

Copilot AI and others added 2 commits April 6, 2026 07:26

Add docstrings step to calkit-run workflow

25fe384

Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/08b57ff7-b66b-4abc-abac-89ada4866851 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Switch Python steps to uv run and remove setup-python

8f06e50

Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/7da3e26b-99ee-4612-a551-42db6102f445 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot AI assigned Copilot and rebeccamccabe Apr 10, 2026

Copilot created this pull request from a session on behalf of rebeccamccabe April 10, 2026 04:30 View session

rebeccamccabe marked this pull request as ready for review April 10, 2026 05:31

Copilot AI review requested due to automatic review settings April 10, 2026 05:31

Merge branch 'main' into copilot/add-docstrings-step-to-calkit-run

7010f1a

Copilot started reviewing on behalf of rebeccamccabe April 10, 2026 05:31 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

Copilot started work on behalf of rebeccamccabe April 10, 2026 06:24 View session

Guard docstrings push for fork PRs, narrow staged files to *.m, add p…

5c10afe

…ull --rebase retry Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/3dd0a364-c68b-4765-9248-f7827c479e19 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot finished work on behalf of rebeccamccabe April 10, 2026 06:27

Copilot AI requested a review from rebeccamccabe April 10, 2026 06:27

Copilot started work on behalf of rebeccamccabe April 10, 2026 06:27 View session

Pin Python 3.12 via setup-uv python-version to guarantee interpreter …

97d09d6

…for uv run steps Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/6d07ea9c-f939-4dc2-bdeb-15e7d5a15c29 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot finished work on behalf of rebeccamccabe April 10, 2026 06:30

rebeccamccabe requested changes Apr 10, 2026

View reviewed changes

Copilot started work on behalf of rebeccamccabe April 10, 2026 06:55 View session

Remove commit/push from docstrings step; include *.m and fork guard i…

a0e58dc

…n calkit save Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/040712ef-0a07-426a-bf74-541b9c73bbb8 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot finished work on behalf of rebeccamccabe April 10, 2026 06:58

Copilot AI requested a review from rebeccamccabe April 10, 2026 06:58

rebeccamccabe and others added 2 commits April 12, 2026 17:02

Merge branch 'main' into copilot/add-docstrings-step-to-calkit-run

9105761

Run pipeline

9bd6292

rebeccamccabe reviewed Apr 13, 2026

View reviewed changes

Rename variables for distinct autodocs in contourx function

c95d405

Copilot started work on behalf of rebeccamccabe April 15, 2026 01:07 View session

Copilot AI and others added 2 commits April 15, 2026 01:11

Fix incorrect param/return names in contourx.m docstring

d80c641

Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Merge main into copilot/add-docstrings-step-to-calkit-run; bump to v1…

960bdd7

….1.21 Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Copilot finished work on behalf of rebeccamccabe April 15, 2026 01:13

Copilot AI requested a review from rebeccamccabe April 15, 2026 01:13

rebeccamccabe and others added 2 commits April 15, 2026 02:04

Merge branch 'main' into copilot/add-docstrings-step-to-calkit-run

b6cf30b

Run pipeline

91b65a4

Copilot started work on behalf of rebeccamccabe April 17, 2026 05:29 View session

Add before/after DVC status snapshot in docstrings step; force-commit…

4cca5c6

… newly stale stages Agent-Logs-Url: https://github.com/symbiotic-engineering/MDOcean/sessions/2b5f2492-8c47-49ee-9c56-d1c7fd1d6dbf Co-authored-by: rebeccamccabe <32020426+rebeccamccabe@users.noreply.github.com>

Run pipeline

004a7d3

Conversation

Copilot AI commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rebeccamccabe Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rebeccamccabe commented Apr 15, 2026

Uh oh!

Copilot AI commented Apr 15, 2026

Uh oh!

rebeccamccabe commented Apr 15, 2026

Uh oh!

rebeccamccabe commented Apr 17, 2026

Uh oh!

Copilot AI commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 10, 2026 •

edited

Loading