Skip to content

POC: add documentation delta reporting to PR checks - #794

Draft
AlexanderLanin wants to merge 2 commits into
mainfrom
poc/docs-delta-gh-pages-baseline
Draft

POC: add documentation delta reporting to PR checks#794
AlexanderLanin wants to merge 2 commits into
mainfrom
poc/docs-delta-gh-pages-baseline

Conversation

@AlexanderLanin

Copy link
Copy Markdown
Member

What this achieves

This POC adds an automated documentation delta report to same-repository pull request checks and publishes the result as a PR comment alongside the documentation preview.

Why this is necessary

Documentation changes are currently difficult to review from generated output alone. A concise comparison of Sphinx-Needs data and rendered HTML makes affected requirements and pages visible directly in the pull request. The baseline must come from the published documentation revision matching the PR base commit, rather than the latest gh-pages publication.

Changes

  • Add the docs_delta comparison tool and regression tests.
  • Resolve the matching historical gh-pages baseline from GitHub Actions environment data.
  • Run the tool with uv in the local on-pr.yml workflow.
  • Upload and create or update a documentation delta PR comment for same-repository PRs.

This is an exploratory POC and is not intended for merging.

@github-actions

github-actions Bot commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Documentation preview for this pull request is available at:
pr-794: https://eclipse-score.github.io/docs-as-code/pr-794/

Documentation delta

Baseline: https://eclipse-score.github.io/docs-as-code/main
PR preview: https://eclipse-score.github.io/docs-as-code/pr-794

Summary

  • Needs: 0 added, 0 removed, 0 modified, 70 unchanged
  • Rendered pages: 0 added, 0 removed, 5 modified, 45 unchanged

Needs

Rendered HTML pages

Modified (5)

  • how-to/bundles/examples/nested/index.html (old / new)
  • internals/decisions/001-test-results-in-workflow.html (old / new)
  • internals/requirements/requirement_coverage.html (old / new)
  • internals/requirements/requirements.html (old / new)
  • internals/requirements/tooling_verification.html (old / new)

@MaximilianSoerenPollak

Copy link
Copy Markdown
Contributor

Needs

Rendered HTML pages

Modified (5)

  • how-to/bundles/examples/nested/index.html (old / new)
  • internals/decisions/001-test-results-in-workflow.html (old / new)
  • internals/requirements/requirement_coverage.html (old / new)
  • internals/requirements/requirements.html (old / new)
  • internals/requirements/tooling_verification.html (old / new)

A bit confused by this.
Nothing changed? Or am I blind as always?

@AlexanderLanin

Copy link
Copy Markdown
Member Author

Yeah.... This is a non functional POC ;-) Enough to discuss the idea.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

2 participants