Fix multi-version GitHub Pages docs deployment

[yuecideng]

Description

This PR fixes multi-version documentation deployment on GitHub Pages. Release tag docs were lost on subsequent main pushes because tag-scoped Actions caches are not visible to default-branch workflows, and each deploy replaces the entire site artifact.

Changes:

• Add docs/scripts/merge_published_site.py to copy missing version directories from the live Pages site (or a local mock in tests) before each CI docs build.
• Run merge after cache restore in main.yml; skip the version being rebuilt (main or the release tag).
• Save the full-site Actions cache only on main pushes (default-branch scope).
• Set environment: github-pages on the publish job.
• Add pytest coverage in tests/docs/ and extend the Test docs publish logic workflow with a main-after-tag scenario.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which improves an existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality will not work without user modification)
• Documentation update

Screenshots

N/A (CI/docs infrastructure)

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• Dependencies have been updated, if applicable.

Test plan

• pytest tests/docs -q --confcutdir=tests/docs
• Run Test docs publish logic workflow (workflow_dispatch) on GitHub after merge
• Verify next main push retains existing release version dirs on https://dexforce.github.io/EmbodiChain/

Made with Cursor