PML-202 : publish multiversion documentation to OVH with citations count

[CassNot]

Summary

Add a GitHub Actions workflow that builds and publishes the Merlin multiversion documentation to OVH S3-compatible Object Storage.

The documentation is published after changes are merged into main.
The workflow can also be launched manually from the main branch.

Changes

• Add .github/workflows/publish-docs.yml.
• Fetch citation counts from OpenAlex before building.
• Strictly validate the current documentation with Sphinx warnings treated as errors.
• Check out the complete Git history and build documentation directly from repository release tags, without relying on an upstream remote.
• Build the latest patch release from each minor series.
• Inject refreshed citation counts into release tags that support citation tracking.
• Upload docs/build/html/ to the configured OVH S3 prefix.
• Remove obsolete objects from the destination using aws s3 sync --delete.
• Prevent concurrent documentation deployments.
• Add tests for citation-data injection and compatibility with older tags.

Deployment triggers

The publication workflow runs on:

• pushes to main, including PR merges;
• manual workflow dispatches from main.

Pull requests continue to use the existing documentation validation (no multiversion, just current origin branch) workflow and do not upload anything to OVH.

GitHub configuration

I created a GitHub environment named documentation, restricted to main.

Environment secrets

• OVH_S3_ACCESS_KEY
• OVH_S3_SECRET_KEY

Environment variables

• S3_REGION
• S3_ENDPOINT
• S3_BUCKET_PATH, for example s3://merlin-docs/html/
• OPENALEX_MAILTO : the citation-fetch script sends it to OpenAlex as the mailto query parameter. It helps OpenAlex identify API traffic and historically qualified requests. I added the merlin email.

The OVH deployment credential needs permission to:

• list the documentation bucket;
• upload and replace objects;
• delete obsolete objects;
• set public-read object ACLs.
  @adi-khot , is it set on OVH ?

Deployment safety

The workflow validates all required S3 configuration before uploading.

The live destination is synchronized with --delete, so obsolete pages and versions are removed from the current html/ prefix. Deployments are serialized to prevent two synchronization operations from running concurrently.

@adi-khot , I was also wondering if bucket versioning or lifecycle rules could be set-up on OVH (for instance a 90-day lifecycle rule to avoid the storage to grow indefinitely (to apply on html/ prefix). I added #TODO comments regarding that in the workflow document.

Proposed OVH retention policy

Once bucket versioning is enabled, the proposed lifecycle policy would:

• retain noncurrent versions for 90 days;
• apply only to objects under html/;
• remove expired delete markers;
• leave the current published documentation untouched.

Open questions for reviewers (about lifecycle)

• Is versioning already enabled on the OVH documentation bucket?
• Should enabling bucket versioning be required before this PR is merged?
• Should the workflow explicitly verify that bucket versioning is enabled and fail before aws s3 sync --delete if it is not?
• Do we agree on retaining noncurrent documentation versions for 90 days?
• Should the lifecycle rule apply only to the html/ prefix?
• Are there existing lifecycle rules on the bucket that must be preserved?

Validation

• pytest -q tests/docs/test_build_multiversion.py tests/docs/test_citations.py
  • 11 tests passed.
• Full multiversion build completed for:
  • 0.1
  • 0.2
  • 0.3
  • 0.4
• Strict tracked-tag build completed for 0.4.1.
• Refreshed citation data was present in the generated 0.4 documentation.
• Workflow YAML parsed successfully.
• git diff --check passed.

Historical 0.2 documentation emits existing Sphinx warnings. These warnings
remain visible but are not fatal during the historical multiversion build.
Current documentation is still validated with warnings treated as errors.