Skip to content

Feat: Add Reference Docs Versioning #1663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
buzzamus wants to merge 2 commits into
base: main
Choose a base branch
from
+78 −3
Open

Feat: Add Reference Docs Versioning #1663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef11470
feat: Add Reference Docs Versioning
buzzamus Aug 4, 2026
1289039
Fix: Change docs branch to gh-pages to match iOS
buzzamus Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
Expand All @@ -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 gh-pages:gh-pages || true
./scripts/publish-docs.sh "${RELEASE_VERSION}"
git -C "$(dirname "$PWD")/$(basename "$PWD")-gh-pages" push origin gh-pages

create_github_release:
needs: [ bump_version ]
Expand Down
5 changes: 3 additions & 2 deletions build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 gh-pages branch instead of committing it into main
outputDirectory.set(project.file("build/dokkaDocs"))
}

subprojects {
Expand Down
67 changes: 67 additions & 0 deletions scripts/publish-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
#!/usr/bin/env bash
# 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 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 <version>}"
BRANCH="gh-pages"

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

@noguier noguier Aug 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script looks great, but i have difficulty parsing through this conditions.
As far as I understand we first check if this directory already exist,
if not we check if the local branch with that name exists,
if it does we add it to the new folder,
if not we create a orphaned new branch.

Is that roughly correct?

@buzzamus buzzamus Aug 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pretty much yep! It checks to see if it already exists in the git worktree and if it is just use it, otherwise create it. This is to ensure it is idempotent and really only have to worry about setup on first run then after that a new version folder is added on each run

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 gh-pages 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'
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="refresh" content="0; url=current/index.html">
<link rel="canonical" href="current/index.html">
</head>
<body>
Redirecting to <a href="current/index.html">latest reference docs</a>...
</body>
</html>
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}"
Loading