Fix broken relative links in README and CHANGELOG for both GitHub and Sphinx

[rohitshinde08]

Fixes #2526

This PR resolves the broken relative links in README.md and CHANGELOG.md when rendered on GitHub, while ensuring they continue to work correctly within the Sphinx documentation build.

The Solution

I have implemented a dual-context solution:

1. GitHub Context: README.md and CHANGELOG.md now use docs/ paths. Since these files sit at the repository root, these links now resolve correctly on GitHub.
2. Sphinx Context: Added a build hook in docs/conf.py that generates temporary Sphinx-friendly include files (_readme_include.md and _changelog_include.md). This hook strips the docs/ prefix from relative links during the build process.
3. Internal Documentation: Updated docs/index.rst and docs/changelog.rst to include these generated files.

This approach ensures that both GitHub visitors and ReadTheDocs readers have a seamless experience with working internal links.

Changes

• README.md / CHANGELOG.md: Updated relative links to use docs/ prefix.
• docs/conf.py: Added builder-inited and build-finished hooks to handle the dynamic link rewriting for Sphinx.
• docs/index.rst / docs/changelog.rst: Switched to using the generated include files.
• .gitignore: Added the generated _include files to prevent accidental commits.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.15%. Comparing base (5e24c24) to head (b0fcc67).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2530   +/-   ##
=======================================
  Coverage   99.15%   99.15%           
=======================================
  Files          41       41           
  Lines        3090     3090           
  Branches      668      668           
=======================================
  Hits         3064     3064           
  Misses         14       14           
  Partials       12       12           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[DanielNoord]

Can we put the generated files in _build to keep the gitignore (and all generated files) in the same place?

Rest of this LGTM from a first glance.

[DanielNoord]

Can you look into the failing docs build? :)

[rohitshinde08]

Can you look into the failing docs build? :)

Hey Daniel! I've updated the PR with the requested type annotations.

Regarding the failing build: it turns out Sphinx excludes the _build folder by default, which was causing the include failure on RTD. I've moved the generated files to a new generated/ directory (added to .gitignore) and switched to absolute paths to make the build rock-solid.

Let me know if everything looks good now! :)