Fix doxygen pages

[vortex-wq]

Fixes #3913

Changes

• Enable Doxygen HTML generation
• Fix Doxygen output directory configuration
• Add GitHub Actions workflow for automatic documentation publishing
• Begin migration away from the legacy ReadTheDocs/Sphinx pipeline

The existing repository still contains legacy ReadTheDocs/Sphinx configuration (conf.py, Breathe/Exhale setup). This PR focuses on establishing the GitHub Pages publishing workflow first; additional cleanup/removal can follow based on maintainer preference.

Validation

• Verified local Doxygen HTML generation
• Verified generated HTML renders correctly in browser
• Verified GitHub Actions workflow execution successfully

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: vortex-wq / name: Vaastavi (50ddf85, d6433f7, f9d9bec)

[lalitb]

Can we add destination_dir: docs here? Otherwise this action publishes to the root of gh-pages and may remove the existing benchmark data already stored on that branch.

[lalitb]

we can remove this branch ?

[lalitb]

@vortex-wq - Have you tested the generated Pages output from your fork? Since this PR does not create an upstream preview, could you share the rendered URL or an uploaded HTML artifact so we can review how the Doxygen docs look before merge?

EDIT - also check the CI failures related to the changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.00%. Comparing base (ec8cd03) to head (933113f).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4099      +/-   ##
==========================================
- Coverage   82.01%   82.00%   -0.01%     
==========================================
  Files         385      385              
  Lines       16030    16030              
==========================================
- Hits        13145    13143       -2     
- Misses       2885     2887       +2     

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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

[vortex-wq]

@vortex-wq - Have you tested the generated Pages output from your fork? Since this PR does not create an upstream preview, could you share the rendered URL or an uploaded HTML artifact so we can review how the Doxygen docs look before merge?

Yes, I have tested it on my local computer.

Rendered preview URL:
https://vortex-wq.github.io/opentelemetry-cpp/
The generated Doxygen HTML is being published correctly through GitHub Pages.

[lalitb]

https://vortex-wq.github.io/opentelemetry-cpp/
The generated Doxygen HTML is being published correctly through GitHub Pages.

Thanks for sharing, this looks awesome . Do you know why it shows/renders older version 1.0.0.-rc2?

[vortex-wq]

https://vortex-wq.github.io/opentelemetry-cpp/
The generated Doxygen HTML is being published correctly through GitHub Pages.

Thanks for sharing, this looks awesome . Do you know why it shows/renders older version 1.0.0.-rc2?

Oh, I noticed it right now, I have only converted/worked upon the older version so currently docs/public/conf.py still contains legacy Sphinx/Breathe/Exhale configuration, and the generated docs inherit the older project metadata/version values from the existing setup.

[lalitb]

Should I work on changing it to existing version or migrating it to the most recent one?

Yes, I believe it should be the latest.

@vortex-wq - For this PR, please make the generated Pages output reflect the version of the source being published. Since this workflow publishes from main, it should use the current repo/dev version from the checked-out source, not the old hardcoded 1.0.0-rc2 value.

Separately, we @open-telemetry/cpp-maintainers should decide the longer-term versioning model for GitHub Pages. RTD gives us version-specific docs URLs today, while this workflow appears to publish only the current generated output. We should decide whether Pages is intended to host only current main docs, or whether we also want release/tag docs with stable versioned URLs in a follow-up.

[lalitb]

Should I work on changing it to existing version or migrating it to the most recent one?

Yes, I believe it should be the latest.

@vortex-wq - For this PR, please make the generated Pages output reflect the version of the source being published. Since this workflow publishes from main, it should use the current repo/dev version from the checked-out source, not the old hardcoded 1.0.0-rc2 value.

Separately, we @open-telemetry/cpp-maintainers should decide the longer-term versioning model for GitHub Pages. RTD gives us version-specific docs URLs today, while this workflow appears to publish only the current generated output. We should decide whether Pages is intended to host only current main docs, or whether we also want release/tag docs with stable versioned URLs in a follow-up.

@vortex-wq - I updated this comment, just in case you miss it.