Skip to main content

release-docs-stage.py

release-docs-stage.py builds the documentation and deploys it to the asf-staging branch, making it available on the staging website.

What It Does​

The script:

  1. Checks that git is configured with the ASF committer identity, and warns when the docs checkout is not on a branch or is behind its upstream
  2. Runs build-docs.py with --staging flag to build documentation for staging
  3. Clones (or updates) a sibling ../asf-staging/ checkout
  4. Checks out the asf-staging branch (or creates it if it doesn't exist)
  5. Removes all existing files (except .git)
  6. Copies the built documentation from juneau-docs/build into it
  7. Adds and commits the changes
  8. Pushes to the remote asf-staging branch

Usage​

Deploy to Staging​

python3 scripts/release-docs-stage.py

Custom Commit Message​

python3 scripts/release-docs-stage.py --commit-message "Updated API documentation"

Test Without Pushing​

python3 scripts/release-docs-stage.py --no-push

Command-Line Options​

  • --no-push - Build and commit but don't push to remote
  • --commit-message MESSAGE - Custom commit message (default: "Deploy documentation staging")
  • --juneau-root DIR - Juneau source checkout, passed on to build-docs.py (default: JUNEAU_ROOT, then a sibling ../master/, then a sibling ../juneau/)
  • --console full|board|none - Console output when the live view is available (default: JUNEAU_TERMINAL_CONSOLE, then board)

Live View​

When the Juneau checkout includes juneau-terminal, the whole run is one live view: Prechecks (identity and branch), the rows of build-docs.py (Clean through Links), Stage push (fetch, copy, commit and push, with the push shown as skipped under --no-push), and URL, the staged site. Without juneau-terminal the script prints plain output, as build-docs.py does.

Prerequisites​

  • Python 3.10 or higher
  • Git (git command must be in PATH)
  • All prerequisites for build-docs.py (Node.js, npm, Maven, Java)
  • Write access to the remote repository

Exit Codes​

  • 0 - Success
  • 1 - Error occurred

Notes​

  • The script uses a persistent sibling ../asf-staging/ checkout for git operations, reused by later runs
  • With --no-push the commit stays in ../asf-staging/ for manual inspection; nothing changes on the remote
  • The script sets SITE_URL environment variable to https://juneau.staged.apache.org when building
  • A success sound is played when the script completes successfully

Workflow​

This script is typically used as part of the documentation release workflow:

  1. Make documentation changes
  2. Run release-docs-stage.py to deploy to staging
  3. Review the staging site
  4. Run release-docs.py to promote to production