docs(#523): Automate version numbers in documentation

[najuna-brian]

Description

Fixes #523

This PR addresses the issue by implementing automatic version detection and substitution in the documentation build process.

Testing

Verified locally that @VERSION_3X@ is correctly substituted with the current version (3.7-fd2f83f-20251010T213229Z-SNAPSHOT) during docs/mdoc generation.

[najuna-brian]

Hi @armanbilge, @valencik

I'm seeing a CI failure that appears to be unrelated to the changes in this PR.
The error shows: scalafmt: [v3.9.4] failed to download [/home/runner/work/cats-effect/cats-effect/.scalafmt.conf]

However, I've verified locally that:
The .scalafmt.conf file is present and correct
All formatting checks pass (sbt scalafmtCheck)
The documentation generation works perfectly (sbt "docs/mdoc")

Could the error message be misleading since scalafmt reads config files from the filesystem rather than downloading them? This looks like a temporary CI infrastructure issue.

Could you please re-run the CI job or let me know if there's something I'm missing?
Thanks 😊

[armanbilge]

Thanks for working on this!

Verified locally that @VERSION_3X@ is correctly substituted with the current version (3.7-fd2f83f-20251010T213229Z-SNAPSHOT) during docs/mdoc generation.

On this branch, the current version is v3.7.0-RC1:
https://github.com/typelevel/cats-effect/releases/tag/v3.7.0-RC1

[najuna-brian]

On this branch, the current version is v3.7.0-RC1:
https://github.com/typelevel/cats-effect/releases/tag/v3.7.0-RC1

Thanks for the clarification! Just to confirm: when there's a release tag like v3.7.0-RC1,
should the automation detect that instead of the development snapshot version I saw locally (3.7-fd2f83f-20251010T213229Z-SNAPSHOT)?

Or are both correct depending on the context? Want to make sure the version detection is working as expected.
@armanbilge