Publish API Documentation

[svrnm]

While working on open-telemetry/opentelemetry.io#5190 I recognized that PHP has no API Docs published, similar to what other languages have. I did a quick test run locally and it seems that by using phpdocumentor a basic version can be created without a lot of effort

Is this something the SIG PHP is interested in? If so, I can provide a PR for generation of the docs.

What remains is to decide where the docs will be published. As you can see from the PR preview @ https://deploy-preview-5190--opentelemetry.netlify.app/api-docs/ different SIGs use different locations for that. I am not sure if there is a official or semi-offical place for php docs (like docs.rs for rust, https://hexdocs.pm for erlang, etc.), since this would be the best place for that. Otherwise, github pages is one option, or we can use netlify, which we also use to run opentelemetry.io

[brettmc]

Hi @svrnm I think it's a good idea to publish our API docs. I think in the PHP world it would be either readthedocs.io or github pages (it's not really documentation, so perhaps github pages is the better option?)

[svrnm]

Hi @svrnm I think it's a good idea to publish our API docs. I think in the PHP world it would be either readthedocs.io or github pages (it's not really documentation, so perhaps github pages is the better option?)

Python, C++ are using readthedocs already, but they also make use of the additional features you get from rdt:

• https://opentelemetry-cpp.readthedocs.io/en/latest/ (see rtd documentation is out of date opentelemetry-cpp#3059 for an ongoing disucssion as well)
• https://opentelemetry-python.readthedocs.io/en/latest/

There is currently no CNCF owned (or otel community) owned rdt account from what I know, so both run independently and if you do not have an adblocker show ads. However this is something we can look into changing.

Node.JS is using github pages:

• https://open-telemetry.github.io/opentelemetry-js/

I ran a small experiment with the C++ docs (and I can do one for PHP as well), publishing the docs using netlify (which we use for opentelemetry.io and is paid by CNCF). It works very similar to github pages, so it can build from each commit or via a github action. The advantage is that we could use opentelemetry.io as part of the domain¹.

Independent from the location I can prepare a PR for phpdocumentor to build the docs

Footnotes

1. full transparency: I am a little bit excited about this opportunity/possibility to hose something like opentelemetry.io/api-docs/<language>, either with redirects or preferable without :-) ↩

[brettmc]

publishing the docs using netlify

I'd be happy with that, and I see benefit in the API docs living under opentelemetry.io via netflify (if that's what you're suggesting)