Skip to content

ci: migrate generated docs to GitHub Pages with PR preview #64

@nh13

Description

@nh13

Problem

The current CI workflow auto-commits "Generate docs files" to PR branches, which causes two issues:

  1. Rebase conflicts on every merge: docs/tools/index.md embeds 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.

  2. Lost GitHub status checks: Commits pushed by GITHUB_TOKEN don'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-pages branch with Jekyll (modernist theme) to host docs at https://fulcrumgenomics.github.io/fgsv/
  • PR previews: Use rossjrw/pr-preview-action to deploy doc previews for each PR (same as fgbio)
  • Main push: Auto-generate and deploy docs to gh-pages on merge to main
  • Independent test job: Remove needs: docs dependency 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/*.md and docs/04_Metrics.md move to gh-pages only; add to .gitignore
  • Keep hand-written docs on main: docs/01_Introduction.md, docs/02_Installation.md, docs/03_Contributing.md stay 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/checkout from 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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions