From ef11470f7465a9a84c10bd98c64c0623fcb9b109 Mon Sep 17 00:00:00 2001 From: buzzamus Date: Tue, 4 Aug 2026 10:45:55 -0500 Subject: [PATCH 1/2] feat: Add Reference Docs Versioning --- .github/workflows/release.yml | 9 ++++- build.gradle | 5 +-- scripts/publish-docs.sh | 67 +++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 3 deletions(-) create mode 100755 scripts/publish-docs.sh diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 78ce627b35..12ef984a81 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -308,7 +308,6 @@ jobs: ./gradlew -PversionParam="${RELEASE_VERSION}" changeREADMEVersion ./gradlew -PversionParam="${RELEASE_VERSION}" changeMigrationGuideVersion ./gradlew -PversionParam="${RELEASE_VERSION}" updateCHANGELOGVersion - ./gradlew dokkaHtmlMultiModule git add -A git commit -am "Release ${RELEASE_VERSION}" git tag "${RELEASE_VERSION}" -a -m "Release ${RELEASE_VERSION}" @@ -317,6 +316,14 @@ jobs: ./gradlew incrementVersionCode git commit -am 'Prepare for development' git push origin ${GITHUB_REF_NAME} "${RELEASE_VERSION}" + - name: Generate Reference Docs + run: ./gradlew dokkaHtmlMultiModule + - name: Publish Reference Docs + run: | + set -euo pipefail + git fetch origin reference-docs:reference-docs || true + ./scripts/publish-docs.sh "${RELEASE_VERSION}" + git -C "$(dirname "$PWD")/$(basename "$PWD")-reference-docs" push origin reference-docs create_github_release: needs: [ bump_version ] diff --git a/build.gradle b/build.gradle index d163d16350..8488ff99b3 100644 --- a/build.gradle +++ b/build.gradle @@ -129,8 +129,9 @@ subprojects { } dokkaHtmlMultiModule.configure { - // redirect dokka output to GitHub pages root directory - outputDirectory.set(project.file("docs")) + // generate into a gitignored build directory; scripts/publish-docs.sh publishes + // this to the reference-docs branch instead of committing it into main + outputDirectory.set(project.file("build/dokkaDocs")) } subprojects { diff --git a/scripts/publish-docs.sh b/scripts/publish-docs.sh new file mode 100755 index 0000000000..2bcdcfcdfe --- /dev/null +++ b/scripts/publish-docs.sh @@ -0,0 +1,67 @@ +#!/usr/bin/env bash +# Publishes Dokka reference docs for a single version to the reference-docs branch, +# mirroring how braintree_ios publishes Jazzy docs: one folder per version plus +# a `current` symlink to the latest, no version-picker UI. +# +# This script only commits locally to the reference-docs branch checked out in a +# worktree next to the repo. It intentionally does not push - the caller +# (e.g. the release workflow) is responsible for pushing when ready. +set -euo pipefail + +VERSION="${1:?Usage: publish-docs.sh }" +BRANCH="reference-docs" + +REPO_ROOT="$(git -C "$(dirname "${BASH_SOURCE[0]}")" rev-parse --show-toplevel)" +DOCS_SOURCE="${REPO_ROOT}/build/dokkaDocs" +WORKTREE_DIR="$(dirname "${REPO_ROOT}")/$(basename "${REPO_ROOT}")-${BRANCH}" + +if [ ! -d "${DOCS_SOURCE}" ]; then + echo "No generated docs found at ${DOCS_SOURCE}. Run ./gradlew dokkaHtmlMultiModule first." >&2 + exit 1 +fi + +if ! git -C "${REPO_ROOT}" worktree list --porcelain | grep -qx "worktree ${WORKTREE_DIR}"; then + if git -C "${REPO_ROOT}" show-ref --verify --quiet "refs/heads/${BRANCH}"; then + git -C "${REPO_ROOT}" worktree add "${WORKTREE_DIR}" "${BRANCH}" + else + git -C "${REPO_ROOT}" worktree add --orphan -b "${BRANCH}" "${WORKTREE_DIR}" + git -C "${WORKTREE_DIR}" commit --allow-empty -m "Initialize reference-docs branch" --quiet + fi +fi + +rm -rf "${WORKTREE_DIR:?}/${VERSION}" +mkdir -p "${WORKTREE_DIR}/${VERSION}" +cp -R "${DOCS_SOURCE}/." "${WORKTREE_DIR}/${VERSION}/" + +ln -sfn "${VERSION}" "${WORKTREE_DIR}/current" + +# GitHub Pages runs Jekyll on branch deploys by default, which mangles Dokka's +# raw HTML/underscore-prefixed output (e.g. _images) - opt out. +touch "${WORKTREE_DIR}/.nojekyll" + +# A bare directory-of-folders has nothing to serve at the branch root, so +# redirect / to the latest version. +cat > "${WORKTREE_DIR}/index.html" <<'EOF' + + + + + + + + + Redirecting to latest reference docs... + + +EOF + +git -C "${WORKTREE_DIR}" add -A +if git -C "${WORKTREE_DIR}" diff --cached --quiet; then + echo "Nothing new to publish for ${VERSION}." +else + git -C "${WORKTREE_DIR}" commit -m "Publish docs for ${VERSION}" --quiet +fi + +echo "Docs for ${VERSION} committed locally to branch '${BRANCH}' in worktree: ${WORKTREE_DIR}" +echo "Review with: git -C \"${WORKTREE_DIR}\" log --stat -1" +echo "This script does not push. Push manually when ready: git -C \"${WORKTREE_DIR}\" push origin ${BRANCH}" From 12890396f22a079bcc23966324b89ab3bfb38128 Mon Sep 17 00:00:00 2001 From: buzzamus Date: Thu, 6 Aug 2026 09:14:16 -0500 Subject: [PATCH 2/2] Fix: Change docs branch to gh-pages to match iOS --- .github/workflows/release.yml | 4 ++-- build.gradle | 2 +- scripts/publish-docs.sh | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 12ef984a81..392efecf2c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -321,9 +321,9 @@ jobs: - name: Publish Reference Docs run: | set -euo pipefail - git fetch origin reference-docs:reference-docs || true + git fetch origin gh-pages:gh-pages || true ./scripts/publish-docs.sh "${RELEASE_VERSION}" - git -C "$(dirname "$PWD")/$(basename "$PWD")-reference-docs" push origin reference-docs + git -C "$(dirname "$PWD")/$(basename "$PWD")-gh-pages" push origin gh-pages create_github_release: needs: [ bump_version ] diff --git a/build.gradle b/build.gradle index 8488ff99b3..642e9e2289 100644 --- a/build.gradle +++ b/build.gradle @@ -130,7 +130,7 @@ subprojects { dokkaHtmlMultiModule.configure { // generate into a gitignored build directory; scripts/publish-docs.sh publishes - // this to the reference-docs branch instead of committing it into main + // this to the gh-pages branch instead of committing it into main outputDirectory.set(project.file("build/dokkaDocs")) } diff --git a/scripts/publish-docs.sh b/scripts/publish-docs.sh index 2bcdcfcdfe..7a388c12d7 100755 --- a/scripts/publish-docs.sh +++ b/scripts/publish-docs.sh @@ -1,15 +1,15 @@ #!/usr/bin/env bash -# Publishes Dokka reference docs for a single version to the reference-docs branch, +# Publishes Dokka reference docs for a single version to the gh-pages branch, # mirroring how braintree_ios publishes Jazzy docs: one folder per version plus # a `current` symlink to the latest, no version-picker UI. # -# This script only commits locally to the reference-docs branch checked out in a +# This script only commits locally to the gh-pages branch checked out in a # worktree next to the repo. It intentionally does not push - the caller # (e.g. the release workflow) is responsible for pushing when ready. set -euo pipefail VERSION="${1:?Usage: publish-docs.sh }" -BRANCH="reference-docs" +BRANCH="gh-pages" REPO_ROOT="$(git -C "$(dirname "${BASH_SOURCE[0]}")" rev-parse --show-toplevel)" DOCS_SOURCE="${REPO_ROOT}/build/dokkaDocs" @@ -25,7 +25,7 @@ if ! git -C "${REPO_ROOT}" worktree list --porcelain | grep -qx "worktree ${WORK git -C "${REPO_ROOT}" worktree add "${WORKTREE_DIR}" "${BRANCH}" else git -C "${REPO_ROOT}" worktree add --orphan -b "${BRANCH}" "${WORKTREE_DIR}" - git -C "${WORKTREE_DIR}" commit --allow-empty -m "Initialize reference-docs branch" --quiet + git -C "${WORKTREE_DIR}" commit --allow-empty -m "Initialize gh-pages branch" --quiet fi fi