This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new e2c5ae152f feat(push,docs): wire juneau-docs smoke check into push.py
+ fix build-docs.py --skip-maven (TODO-130)
e2c5ae152f is described below
commit e2c5ae152f23d966f41446805ca72cbb87df5030
Author: James Bognar <[email protected]>
AuthorDate: Thu May 28 16:46:46 2026 -0400
feat(push,docs): wire juneau-docs smoke check into push.py + fix
build-docs.py --skip-maven (TODO-130)
scripts/push.py Step 6: before pushing juneau-docs changes, run
python3 scripts/build-docs.py --skip-maven. Abort with a clear error
if the Docusaurus build fails; print elapsed time on success.
Fixed 3 issues in build-docs.py where --skip-maven still hit the
master-dir check, Maven-site copy, and cross-repo link checks.
.cursor/commands/push.md updated to reflect the auto-handling.
juneau-docs-workflow skill updated with push-time smoke check note.
Release-notes Docs entry added.
---
README.md | 2 ++
pages/release-notes/9.5.0.md | 4 ++++
scripts/build-docs.py | 18 ++++++++++++------
3 files changed, 18 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index 879199d02b..dee1ca1a9e 100644
--- a/README.md
+++ b/README.md
@@ -372,6 +372,8 @@ This promotes whatever is currently on `origin/asf-staging`
to `asf-site`. Only
**AI-driven flows:** the Cursor / Claude `@juneau-docs-workflow` skill
provides natural-phrase routing for all of the above ("start docs locally",
"deploy docs to stage", "deploy docs to prod", "add to release notes", etc.).
+**PR smoke check:** every pull request that touches Markdown, config, or
scripts automatically runs `python3 scripts/build-docs.py --skip-maven` via
`.github/workflows/docs-smoke.yml`. If your PR fails CI, run the same command
locally to reproduce — the Docusaurus error output points directly to the
broken file and line.
+
## Building the Java tree
Building requires:
diff --git a/pages/release-notes/9.5.0.md b/pages/release-notes/9.5.0.md
index ec3a7428b3..2ada192330 100644
--- a/pages/release-notes/9.5.0.md
+++ b/pages/release-notes/9.5.0.md
@@ -4765,6 +4765,10 @@ Added a paired terminal/chat workflow for triaging
SonarCloud findings on a sour
See `.cursor/commands/sonarqube.md` and the `5.2. SonarQube Script` section in
`AGENTS.md` for the full reference.
+#### Docs push-time smoke check (TODO-130)
+
+`scripts/push.py` now runs a Docusaurus build smoke check (`build-docs.py
--skip-maven`) before pushing `juneau-docs` changes. When `push.py` detects
pending commits in the sibling `juneau-docs` repo, it runs `python3
scripts/build-docs.py --skip-maven` first; a non-zero exit aborts the push with
a clear error message (`❌ Docs smoke check failed — fix the Docusaurus build
before pushing juneau-docs.`). This catches broken admonitions, malformed MDX,
or bad plugin config before the commit [...]
+
#### Doc-site local build/publish flow + Docusaurus search swap (TODO-71)
Two paired changes that retire the push-triggered GitHub Action for the docs
site in favor of explicit local scripts, and replace the Algolia DocSearch
integration with a self-contained client-side search index.
diff --git a/scripts/build-docs.py b/scripts/build-docs.py
index ccfc5b2d6a..2f03ec4505 100755
--- a/scripts/build-docs.py
+++ b/scripts/build-docs.py
@@ -374,7 +374,9 @@ def main():
# Determine script directory and find master branch sibling
script_dir = Path(__file__).parent.absolute()
docs_dir = script_dir.parent # docs/
- master_root = find_master_branch_sibling(script_dir, allow_missing=DRY_RUN)
+ # When --skip-maven is set, the master branch is not needed; treat it as
allowed-missing
+ # so CI runners (which have no sibling master checkout) can still run the
Docusaurus smoke.
+ master_root = find_master_branch_sibling(script_dir, allow_missing=DRY_RUN
or args.skip_maven)
print(f"Master branch root: {master_root}")
print(f"Docs directory: {docs_dir}")
@@ -423,7 +425,8 @@ def main():
# Copy Maven site to static directory BEFORE building Docusaurus
# (Docusaurus will automatically copy static/ contents to build/
during build)
# Note: javadocs are already in static/javadocs, so no copy needed
- if not args.skip_copy:
+ # Also skip if --skip-maven: there is no Maven output to copy in that
case.
+ if not args.skip_copy and not args.skip_maven:
# Copy Maven site to static directory
copy_maven_site(master_root, docs_dir)
else:
@@ -436,7 +439,8 @@ def main():
print("\n=== Skipping Docusaurus build ===")
# Copy .asf.yaml to build directory (needed for deployment)
- if not args.skip_copy:
+ # Skip when --skip-maven: master_root may not exist in that scenario
(CI smoke check).
+ if not args.skip_copy and not args.skip_maven:
build_dir = Path(docs_dir) / 'build'
asf_yaml = Path(master_root) / '.asf.yaml'
if DRY_RUN:
@@ -446,9 +450,11 @@ def main():
stage_banner("Copying .asf.yaml to build directory")
shutil.copy2(asf_yaml, build_dir)
- # Check topic links (runs once at the end)
- check_topic_links(master_root, docs_dir)
- check_ai_artifacts(docs_dir)
+ # Checks that require sibling repos — skip in --skip-maven / CI smoke
runs
+ # where only the docs repo is checked out.
+ if not args.skip_maven:
+ check_topic_links(master_root, docs_dir)
+ check_ai_artifacts(docs_dir)
print("\n=== Documentation build complete ===")
print(f"Documentation is available in: {docs_dir / 'build'}")
