commit - c42a195b1cde4822b9b0c4f2f86d627a2c9cac15
commit + e88ae7c6d7c509d34868a01984b5cfdc694dc89e
blob - b2d6e93496ebcde0388e04f75ff507c8821c17cc
blob + d1d8185fadee01064844666059fbec39444dffab
--- .github/workflows/Documenter.yml
+++ .github/workflows/Documenter.yml
-# 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
- 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()
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' \
+ '<!--This file is automatically generated by DocumenterVitepress.jl-->' \
+ '<meta http-equiv="refresh" content="0; url=./dev/"/>' \
+ > "$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
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
],
],
)
-
-# 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/<n>/`
-# (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,
-)
