Swatantra-66 opened a new pull request, #194:
URL: https://github.com/apache/nuttx-website/pull/194
## Summary
Decouples the monolithic website and documentation build pipeline in
`.github/workflows/main.yml` into two independent, parallel jobs to resolve
#180.
Previously, website generation (Jekyll/Ruby) and documentation compilation
(Sphinx/Python) ran within a single monolithic job where artifacts were
uploaded at the end. When Sphinx documentation encountered build errors, the
entire workflow halted, completely blocking website updates, download link
fixes, and release announcements (such as the historical issue seen in #179
during the NuttX 13.0.0 release).
## Key Changes
1. **Two Decoupled Workflow Jobs in `.github/workflows/main.yml`:**
- **`build-website`**: Builds the Jekyll static site using Ruby/Bundler
and deploys to `asf-site` while strictly preserving existing `content/docs/`.
Runs on website PRs and commits, completing in ~1-2 minutes. Skips scheduled
doc crons and NuttX core doc dispatch events.
- **`build-docs`**: Builds Sphinx documentation using Python/Pipenv,
PlantUML, and the incremental release doc restoration engine from #193,
deploying compiled documentation to `content/docs/` independently.
2. **Modular `publish.sh`:**
- Adds `--website` (`-w`) mode: builds Jekyll into `target/`, checks out
`asf-site`, and safely stages `content/` while backing up and restoring
existing `content/docs/`.
- Adds `--docs` (`-d`) mode: safely moves compiled `docs/` across the
branch switch and stages `content/docs/` without touching website HTML pages.
- Adds directory guards (`if [ ! -d "target" ]; then exit 1; fi`) to
prevent destructive `rm -rf content` operations on failed builds.
- Uses `cp -a "$TEMP_STAGE_DOCS/docs/." content/docs/` to safely handle
hidden files and empty directory edge cases.
- Preserves `--all` (`-a`) default mode for local development.
3. **Concurrency Control:**
- Configures top-level workflow concurrency (`group: asf-site-publish,
cancel-in-progress: false`) ensuring sequential, collision-free deployments to
the `asf-site` branch.
- Uses `git pull --rebase origin asf-site` before pushing to guarantee
clean branch rebasing.
4. **Dedicated Artifacts:**
- Uploads `website-site` from the website job and `docs-site` from the
documentation job, allowing reviewers to preview each artifact independently.
## Impact
- Website PR review loops and deployment times drop from 30+ minutes down to
~1-2 minutes.
- Website releases and announcements can never be blocked by Sphinx doc
build issues.
## Testing
- Validated `publish.sh` syntax via `bash -n publish.sh`.
- Validated `.github/workflows/main.yml` syntax via PyYAML parser.
- Verified clean git working tree and formatting via `git diff --check`.
Fixes #180
Signed-off-by: Swatantra Yadav <[email protected]>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
