commit e88ae7c6d7c509d34868a01984b5cfdc694dc89e from: ale date: Tue Aug 18 23:46:55 2026 UTC Deploy docs via GitHub Actions Pages artifact, not a gh-pages branch push The GitHub mirror's docs site kept going 404 despite a working CI run: confirmed via GitHub's own repo events that gh-pages gets deleted on every Forgejo mirror sync (same-second DeleteEvent alongside every mirrored push, and even on syncs with no new commits) — the mirror forces GitHub to exactly match Forgejo's origin, which never had that branch to begin with, since it's only ever created by CI running on GitHub itself. No fix on the push side can outrun that; the durable fix is to stop using a branch as the deploy target. docs/make.jl no longer calls deploydocs. The workflow now assembles the already-built Vitepress site (docs/build/1) into the dev/ layout DocumenterVitepress used to write via git, uploads it as a Pages artifact, and publishes with actions/deploy-pages — nothing left for the mirror to touch. commit - c42a195b1cde4822b9b0c4f2f86d627a2c9cac15 commit + e88ae7c6d7c509d34868a01984b5cfdc694dc89e blob - b2d6e93496ebcde0388e04f75ff507c8821c17cc blob + d1d8185fadee01064844666059fbec39444dffab --- .github/workflows/Documenter.yml +++ .github/workflows/Documenter.yml @@ -1,28 +1,23 @@ -# Builds docs/ (Documenter.jl + DocumenterVitepress.jl) and deploys it to -# the gh-pages branch. Mirrors DocumenterVitepress.jl's own workflow -# (github.com/LuxDL/DocumenterVitepress.jl/.github/workflows/Documenter.yml) — -# julia-docdeploy handles the Julia side (Pkg.develop the package into -# docs/, instantiate, run docs/make.jl); DocumenterVitepress bootstraps -# its own Node/Vitepress toolchain, no separate setup-node step needed. +# Builds docs/ (Documenter.jl + DocumenterVitepress.jl) and deploys it via +# GitHub's native "deploy from GitHub Actions" Pages mechanism — an +# artifact upload plus actions/deploy-pages, not a push to a gh-pages +# branch. That branch-push approach (DocumenterVitepress.deploydocs) was +# tried first and kept breaking: this repo's real origin is a self-hosted +# Forgejo instance that mirrors to GitHub, and Forgejo's mirror sync +# forces GitHub to exactly match it — which means it deletes gh-pages on +# every sync, since that branch only ever existed on the GitHub side +# (created by this very workflow). See docs/make.jl's top comment and the +# Investigation Log for the full diagnosis. Publishing straight from a +# workflow artifact has no branch for the mirror to touch. name: Documenter on: push: branches: - main - tags: ['*'] pull_request: workflow_dispatch: -# Needed for deploydocs to push to gh-pages and for GitHub Pages deployment. -permissions: - contents: write - pages: write - id-token: write - statuses: write - -# One deploy at a time; let an in-progress deploy finish rather than -# cancelling it mid-push. concurrency: group: pages cancel-in-progress: false @@ -38,11 +33,12 @@ jobs: - name: Load Julia packages from cache id: julia-cache uses: julia-actions/cache@v3 - - name: Build and deploy docs + - name: Build docs + # Despite the name, this action doesn't deploy anything itself — + # it just runs docs/make.jl (which no longer calls `deploydocs` at + # all; see its top comment). uses: julia-actions/julia-docdeploy@v1 env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # authenticates the push to gh-pages - DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # only needed if GITHUB_TOKEN push is restricted; see README.md JULIA_DEBUG: "Documenter" - name: Save Julia depot cache on cancel or failure if: cancelled() || failure() @@ -50,3 +46,49 @@ jobs: with: path: ${{ steps.julia-cache.outputs.cache-paths }} key: ${{ steps.julia-cache.outputs.cache-key }} + # docs/build/1 is the fully-built Vitepress static site for the + # "dev" base (docs/build/bases.txt lists the bases DocumenterVitepress + # built; this project only ever has one, "dev" — no tagged releases + # yet). Replicates, as plain files instead of a git-branch merge, + # exactly what DocumenterVitepress's own deploydocs used to write at + # the branch root (see DocumenterVitepress.jl's + # postprocess_before_push/write_redirect_index!): a `dev/` subfolder + # holding the site, a root index.html that redirects to it, and + # versions.js for the version-picker widget. + - name: Assemble Pages artifact + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + run: | + set -euo pipefail + site=docs/pages-site + mkdir -p "$site/dev" + cp -r docs/build/1/. "$site/dev/" + touch "$site/.nojekyll" + printf '%s\n' \ + '' \ + '' \ + > "$site/index.html" + printf '%s\n' \ + 'var DOC_VERSIONS = [' \ + ' "dev",' \ + '];' \ + > "$site/versions.js" + - name: Upload Pages artifact + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + uses: actions/upload-pages-artifact@v3 + with: + path: docs/pages-site + + deploy: + needs: build + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 blob - 6d762491e31e1002a53e098a15ebfa9194c728e7 blob + ac796e08ccc95aa709ee8492096cdd77772d876a --- docs/make.jl +++ docs/make.jl @@ -2,6 +2,21 @@ using AsteroidPipeline using Documenter using DocumenterVitepress +# This only builds the site (into docs/build/1 — see bases.txt) and never +# deploys it. Deployment used to be DocumenterVitepress.deploydocs pushing +# to a gh-pages branch, but that branch only ever existed on the GitHub +# mirror (created by CI running there) — never on this repo's real origin +# (a self-hosted Forgejo instance). Forgejo's mirror sync to GitHub forces +# GitHub to exactly match this origin, which means it deletes gh-pages on +# every sync (confirmed directly: GitHub's own repo events show a +# DeleteEvent for gh-pages at the exact same second as every mirrored push, +# and even on syncs with no new commits) — a structural conflict, not +# something fixable by re-deploying harder. The real fix: stop using a git +# branch as the deploy target at all. `.github/workflows/Documenter.yml` +# now assembles the GitHub Pages artifact directly from docs/build/1 and +# publishes it via actions/deploy-pages — nothing left for the mirror to +# delete. + # index.md, investigation-log.md, variable-star-validation.md, # iasc-campaign-validation.md, and design-refinements.md are all real, # permanent, committed pages under docs/src — the docs site's own @@ -52,31 +67,3 @@ makedocs(; ], ], ) - -# GitHub's default Jekyll processing on a branch-based Pages deploy -# silently ignores any path starting with `_` — the standard reason any -# non-Jekyll static site on GitHub Pages needs a `.nojekyll` marker. -# DocumenterVitepress has the code for this (writer.jl, `touch(..., -# "final_site", ".nojekyll")`) but it's commented out in the installed -# version (0.3.5) — confirmed by reading the package source, not assumed. -# A first attempt here touched `.nojekyll` into each `docs/build//` -# (the local per-version build output) before deploydocs — wrong: that -# directory becomes the *nested* `dev/` (etc.) subfolder on gh-pages, not -# its root, and `.nojekyll` only has any effect at the true branch root. -# deploydocs' own git push (see DocumenterVitepress/src/writer.jl) checks -# out the *existing* gh-pages branch and only touches specific known -# paths (each version's own subfolder, versions.js, the root redirect -# index.html) rather than wiping the branch — so a root `.nojekyll` -# added once, directly, persists across every future automated deploy. -# Added that way instead (see the Investigation Log for the real -# gh-pages-was-never-enabled story this was found alongside), not -# reproduced here as build-time logic since there's nothing in the local -# build tree that actually corresponds to the branch's real root. - -DocumenterVitepress.deploydocs(; - repo="github.com/Richard7987/AsteroidPipeline.jl", - target=joinpath(@__DIR__, "build"), - branch="gh-pages", - devbranch="main", - push_preview=true, -)