Docs

[CLHatch]

Pull request

Purpose
Describe the problem or feature in addition to a link to the issues.

Approach
How does this change address the problem?

Open Questions and Pre-Merge TODOs
Check all boxes as they are completed

• Use github checklists. When solved, check the box and explain the answer.

Learning
Describe the research stage
Links to blog posts, patterns, libraries or addons used to solve this problem

Requirements
Check all boxes as they are completed

• These changes meet the standards for contributing.
• I have read the code of conduct.

Summary by Sourcery

CI:

• Change the docs site build workflow to be triggered by completion of the Validate workflow on main rather than by pushes to docs paths, and gate the repository-dispatch step on successful validation.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Updates the docs site build GitHub Action to be triggered by successful completion of the Validate workflow instead of direct pushes to docs-related files on main, and adds a safeguard so the site build is only triggered when the upstream workflow succeeds.

Sequence diagram for updated docs site build trigger workflow

sequenceDiagram
  actor Developer
  participant GitHub
  participant Validate_workflow
  participant Trigger_Site_Build_workflow
  participant Docs_Main_Repo

  Developer->>GitHub: Push to main
  GitHub->>Validate_workflow: Trigger Validate workflow
  Validate_workflow-->>GitHub: Run completes (success or failure)
  GitHub->>Trigger_Site_Build_workflow: workflow_run event (Validate completed)
  Trigger_Site_Build_workflow->>Trigger_Site_Build_workflow: Check github.event.workflow_run.conclusion == success
  alt Validate success
    Trigger_Site_Build_workflow->>Docs_Main_Repo: repository-dispatch (Trigger build)
  else Validate failure
    Trigger_Site_Build_workflow-->>Docs_Main_Repo: No action
  end

Loading

File-Level Changes

Change	Details	Files
Change the trigger for the docs site build workflow to depend on the completion of the Validate workflow rather than file-based push events on main.	Replace push-based trigger with workflow_run-based trigger that monitors the Validate workflow Configure the workflow_run trigger to fire on completed runs of the Validate workflow on the main branch Remove path filters for docs and mkdocs.yml since triggers are now workflow-based	.github/workflows/trigger-site-build.yml
Ensure the site build is only triggered when the Validate workflow succeeds.	Add an if condition to the trigger step to check that github.event.workflow_run.conclusion is success before dispatching Keep the repository-dispatch step configuration but guard it behind the success check	.github/workflows/trigger-site-build.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The branches filter is now at the same level as workflow_run instead of nested under it, so it will be ignored; if you intend to restrict to main, indent branches under workflow_run in the YAML.
• By removing the paths filter for docs/** and mkdocs.yml, this workflow will now trigger for any successful Validate run (not just docs-related changes); if that’s unintended, consider reintroducing equivalent filtering via conditions on github.event.workflow_run.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `branches` filter is now at the same level as `workflow_run` instead of nested under it, so it will be ignored; if you intend to restrict to `main`, indent `branches` under `workflow_run` in the YAML.
- By removing the `paths` filter for `docs/**` and `mkdocs.yml`, this workflow will now trigger for any successful `Validate` run (not just docs-related changes); if that’s unintended, consider reintroducing equivalent filtering via conditions on `github.event.workflow_run`.

## Individual Comments

### Comment 1
<location> `.github/workflows/trigger-site-build.yml:15` </location>
<code_context>
     runs-on: ubuntu-latest
     steps:
       - name: Trigger build in main repo
+        if: ${{ github.event.workflow_run.conclusion == 'success' }}
         uses: peter-evans/repository-dispatch@v3
         with:
</code_context>

<issue_to_address>
**suggestion (performance):** Consider moving the `if` condition to the job level to avoid starting a runner unnecessarily.

As written, the runner is still provisioned even when `Validate` fails, and only this step is skipped. Applying `if: ${{ github.event.workflow_run.conclusion == 'success' }}` at the `trigger` job level will skip the whole job in that case, reducing runner usage and making the workflow’s behavior clearer.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (performance): Consider moving the if condition to the job level to avoid starting a runner unnecessarily.

As written, the runner is still provisioned even when Validate fails, and only this step is skipped. Applying if: ${{ github.event.workflow_run.conclusion == 'success' }} at the trigger job level will skip the whole job in that case, reducing runner usage and making the workflow’s behavior clearer.