-
Notifications
You must be signed in to change notification settings - Fork 1
Open
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or request
Description
Problem
The current CI workflow auto-commits "Generate docs files" to PR branches, which causes two issues:
-
Rebase conflicts on every merge:
docs/tools/index.mdembeds a version+commit hash (e.g.0.2.1-b54e45d), so every open PR's generated docs conflict with main after any merge. This forces manual rebasing of all open PRs. -
Lost GitHub status checks: Commits pushed by
GITHUB_TOKENdon't re-trigger workflows (by design, to prevent infinite loops). So the final commit on every PR branch is the unchecked "Generate docs files" commit, and the test/lint status checks are no longer associated with the HEAD commit.
Proposed Solution
Migrate generated docs from the main branch to a gh-pages branch, following the pattern used by fgbio.
Key changes
- Create a
gh-pagesbranch with Jekyll (modernist theme) to host docs athttps://fulcrumgenomics.github.io/fgsv/ - PR previews: Use
rossjrw/pr-preview-actionto deploy doc previews for each PR (same as fgbio) - Main push: Auto-generate and deploy docs to
gh-pageson merge to main - Independent test job: Remove
needs: docsdependency so tests run independently and status checks are always on the final PR commit - No auto-commits to PR branches: Eliminates rebase conflicts and lost status checks entirely
- Remove generated docs from
main:docs/tools/*.mdanddocs/04_Metrics.mdmove to gh-pages only; add to.gitignore - Keep hand-written docs on
main:docs/01_Introduction.md,docs/02_Installation.md,docs/03_Contributing.mdstay as source-controlled content, copied to gh-pages during CI builds
What stays the same
- Doc generation logic (BuildToolDocs, FgSvMetricsDoclet) is unchanged
- Build scripts (
src/scripts/build_tool_docs.sh,src/scripts/build_metric_docs.sh) remain for local dev use - Unit tests continue to run on push and PR
Additional improvements
- Update
actions/checkoutfrom v2 to v4 - Remove GPG signing infrastructure (no longer needed without auto-commits)
- Landing page on GitHub Pages with badges, install instructions, and links to tool/metric docs
References
- fgbio's implementation: workflow, composite action, live site
rossjrw/pr-preview-action
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or request