rtd documentation is out of date

[t-b]

By accident I found https://opentelemetry-cpp.readthedocs.io/ which according to https://readthedocs.org/projects/opentelemetry-cpp/ is out of date as it has only v.1.13.0 as latest version.

[marcalff]

Thanks for the report.

Read the docs is definitively out of date.

We (opentelemetry-cpp) need to figure out whether to continue using rtd, or to expose the doc in opentelemetry.io.

In either case, some action is needed to make sure the doc is published.

cc @lalitb @svrnm

[lalitb]

Yes, the build has been failing for long. I have an action to debug this, and add other maintainers as admin. Will reply back once it's done by tomorrow.

[svrnm]

What is / was the purpose of using readthedocs? Depending on the content we can see if/how we integrate that into opentelemetry.io directly. Some other language SIGs have API Docs (Java, JavaScript) using a 3rd party place, but exclusively for that

cc @open-telemetry/docs-approvers

[lalitb]

What is / was the purpose of using readthedocs?

This is exclusively for the API docs. Other docs are in opentelelemetry.io.

[svrnm]

What is / was the purpose of using readthedocs?

This is exclusively for the API docs. Other docs are in opentelelemetry.io.

In that case, rdt is fine, although I wonder if we could deploy it via netlify to a *.opentelemetry.io page

[lalitb]

In that case, rdt is fine, although I wonder if we could deploy it via netlify to a *.opentelemetry.io page

Yes indeed. maintaining rtd deployment stack for C/C++ is complex - do we have any doc on getting it done?

[svrnm]

In that case, rdt is fine, although I wonder if we could deploy it via netlify to a *.opentelemetry.io page

Yes indeed. maintaining rtd deployment stack for C/C++ is complex - do we have any doc on getting it done?

This would be a first, so I would need to do some investigation. Can you give me some pointers for the current deployment stack? I figured that there is some parts in docs/public, but how is this published to rtd?

Edit: Here is a sample deployment: https://main--opentelemetry-cpp-api-docs.netlify.app/, I just figured out what commands I need to run for building it. Right now it is configured to build on commit, so everytime a commit is done to this repo the page will be updated.

[lalitb]

. Can you give me some pointers for the current deployment stack? I figured that there is some parts in docs/public, but how is this published to rtd?

Yes, it;s under docs/public, and uses doxygen + sphynx + exhale + breathe, as explained here - https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

The publishing is through a webhook configured in otel-cpp repo.

[svrnm]

. Can you give me some pointers for the current deployment stack? I figured that there is some parts in docs/public, but how is this published to rtd?

Yes, it;s under docs/public, and uses doxygen + sphynx + exhale + breathe, as explained here - devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake

The publishing is through a webhook configured in otel-cpp repo.

Thanks! See my Edit above I got a working copy via netlify: https://main--opentelemetry-cpp-api-docs.netlify.app/, it pulls from this repo on commit, and as of now lacks a few pieces that you have with readthedocs already:

• "Edit on GitHub" links
• That version picker at the bottom of the page (seems to be a RDT exclusive feature for the theme)
• Publication on release: that's something we probably also would need to solve by doing deployments differently

All of that can be fixed, however I will leave it to @open-telemetry/cpp-maintainers, to decide if it is worth the hassle: the upsides using netlify are that you could get it under opentelemetry.io (api-docs.opentelemetry.io/cpp, or cpp-api-docs.opentelemetry.io, ...) for your API docs, you would have no ads (if you turn of your ad blocker, RDT has ads), and you could outsource some of the work to @open-telemetry/docs-maintainers.

[t-b]

Thanks all for tackling this. Having API docs for different versions would be nice though.

[github-actions]

This issue was marked as stale due to lack of activity.