ci: split website build and documentation build into separate jobs

[Swatantra-66]

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 ci: build only affected documentation and preserve historical releases #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 maverickswatantra@gmail.com