Reusable Documentation Workflows by beauremus · Pull Request #17 · fermi-ad/.github

beauremus · 2025-10-28T02:39:02Z

My first pass attempt at automating source documentation for Dart and Rust.

jacob-curley-fnal · 2025-10-28T14:14:35Z

+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}


Both workflows reference this steps.deployment.outputs.page_url variable. I think I'm missing where that comes from. Is that set by some other workflow?

Great catch! I used the example from the Action readme, but I don't think we need this anymore. Will push an update shortly.

I added an id: to the step. So, this output is generated by the Action.
What I'm not sure of is whether the environment needs to exist before being requested.
https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments

I'll merge after you approve

I think the environment is set before the steps execute. So your url variable might just be empty

Does the deploy-pages action require a url environment variable? Is that how that works?

This is part of the README docs, but there's no further explanation.
https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments
This doc doesn't have it. So, let's remove the complexity until it's better understood.

Looking more closely at the actions/deploy-pages README, it seems like maybe the purpose is to kick out an auto-generated URL somewhere that a person could see it? Like, maybe the action comes up with the URL internally, so you'd need to have it reported into the environment variable in order to know where to look for the deployed pages?

I'm not sure there's some magic going on for sure. Without diving into the Action code, I'm not sure.

jacob-curley-fnal

Just had that one clarification question, but otherwise looks solid!

jacob-curley-fnal · 2025-10-28T16:39:31Z

+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: dpeloyment


may want to check spelling here

We need a linter/spell checker 😳

jacob-curley-fnal · 2025-12-19T18:36:23Z

+permissions:
+  pages: write     # Needed to deploy
+  id-token: write  # Needed for auth


Probably need a contents: read entry as well. I'm getting errors when trying to call this, as default behavior is to only set the permissions that are provided here, and to try to use the lowest level permissions possible. My suspicion is that GitHub sees this as us "downgrading" the permissions from the calling workflow, since read is not specified. So it's dropping the read permissions and can't see the code in the repo anymore.

This will apply to all workflows. Right?

Any workflow that specifies permissions at this level, yes. The integration and deployment workflows just expect to have their permissions provided. They don't have any special permissions block like this.

Got a successful deployment! Only problem is that the permissions on the pages site are jank, so I can't access the actual docs 😆 Might be a problem at the repo level tho, or with the org permissions

Need to figure out the best way to consistently handle the URLs. I found the docs here https://studious-spoon-gz98yym.pages.github.io/reference/rust_env_var_lib/index.html 😅
Not great

Need to figure out how to resolve the snake case package name for this step:

cp -r target/doc/* ./docs/reference

It should be

cp -r target/doc/rust_env_var_lib/* ./docs/

rneswold

This is awesome, Beau! I love having our docs available!

rneswold · 2025-12-22T19:30:42Z

Should we have it run a docs check pass in the PR and generate the docs when merging? (Is that what it does now?)

jacob-curley-fnal · 2026-01-05T16:44:14Z

Ran into an issue while trying to use this in rust-pubsub-lib
When a Rust project uses a Fermi-internal Rust lib, it is not able to pull it into the project during cargo's doc command (even tho we're skipping the dependencies, it still wants to build the full project). Might need a flag similar to the integration workflow that triggers the use of the external git CLI rather than cargo's internal git adapter

Create two reusable workflows, one each for Dart and Rust to build and deploy their docs using GitHub Pages.

The url field in the environment and the id: deployment from the actions/deploy-pages@v4 step are no longer necessary as the action automatically sets the page URL. This commit cleans up these redundant configurations in both the Dart and Rust documentation deployment workflows.

…r Rust deps on internal repos

jacob-curley-fnal · 2026-01-28T16:07:19Z

@beauremus Rebased your branch on the latest from main and took a stab at setting up the needed steps for using submodules and internal repos - feel free to revert or make further changes

Copilot

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Moved to latest versions of actions that support Node 24 where possible, and updated the docs to include all features by default

beauremus requested review from cnlklink, jacob-curley-fnal, mgonzal1, mguzman04 and rneswold October 28, 2025 02:39

jacob-curley-fnal reviewed Oct 28, 2025

View reviewed changes

Comment thread .github/workflows/deploy-rust-docs.yaml

jacob-curley-fnal approved these changes Oct 28, 2025

View reviewed changes

mguzman04 approved these changes Oct 28, 2025

View reviewed changes

jacob-curley-fnal reviewed Oct 28, 2025

View reviewed changes

jacob-curley-fnal reviewed Dec 19, 2025

View reviewed changes

rneswold approved these changes Dec 22, 2025

View reviewed changes

beauremus and others added 11 commits January 28, 2026 09:57

feat: ✨ Create reusable workflows for deploying documentation.

2fc9a5e

Create two reusable workflows, one each for Dart and Rust to build and deploy their docs using GitHub Pages.

docs: 📝 Add description of docs workflow usage.

f852959

fix: 🐛 Remove extraneous backticks.

857e82f

docs: 📝 Add context for repo config required to use Action.

f9a277e

fix: 🔥 Remove unused inputs.

d5e22b7

fix: 🐛 Add step id that's referenced in the environment.

7bed0d4

fix: 🐛 Typo in id.

6ec336e

Add read permission for repo contents in workflow

4e0835f

Add permissions for GitHub Pages deployment

fc9f89e

Add recursive pull for repos with git submodules and configuration fo…

3e98f98

…r Rust deps on internal repos

jacob-curley-fnal force-pushed the documentation-workflow branch from 7487152 to 3e98f98 Compare January 28, 2026 16:05

Update install command to include package update

75e45bf

Copilot AI review requested due to automatic review settings March 13, 2026 22:13

Copilot AI reviewed Mar 13, 2026

View reviewed changes

Update GitHub Actions workflow for Rust docs

6e7454e

Moved to latest versions of actions that support Node 24 where possible, and updated the docs to include all features by default

Conversation

beauremus commented Oct 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beauremus Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jacob-curley-fnal left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rneswold left a comment

Choose a reason for hiding this comment

Uh oh!

rneswold commented Dec 22, 2025

Uh oh!

jacob-curley-fnal commented Jan 5, 2026

Uh oh!

jacob-curley-fnal commented Jan 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

beauremus Oct 28, 2025 •

edited

Loading