Host PHP API Docs via netlify

[svrnm]

This is step 2 and a follow up to open-telemetry/opentelemetry-php#1378:

PHP is one of the few languages¹ that does not have API Docs published yet. I provided a PR that adds phpDocumentor to the repo which creates the API Docs. What remains is where and how to host them. My proposal is that we host them via netlify, as this comes with a few advantages:

• PHP SIG does not need to do their own hosting (via readthedocs, github pages), or maintain workflows, since this is covered by SIG Comms and netlify can pick up changes via commits similar to how the opentelemetry.io page is built today.
• We can provide a *.opentelemetry.io location (php.api-docs.opentelemetry.io or opentelemetry.io/api-docs/php with a rewrite proxy)

What needs to be done:

• Go into the netlify console, setup a new page (e.g. php.api-docs.opentelemetry.io), point it to opentelemetry-php repo, let it run
• Setup the rewrite proxy for opentelemetry.io/api-docs/php
• That's it :-)

Note, that this can also be a pilot and if this works well, we can provide something similar to other SIGs.

cc @open-telemetry/php-approvers @open-telemetry/docs-approvers

Footnotes

1. only other language is swift ↩

[chalin]

Overall, I like the idea of hosting via Netlify.

I'd like to suggest that the PHP API reference have the following canonical path:

• /docs/languages/php/api

Just like for other languages. We can then separately decide what kind of aliasing we might want to have (or not have). WDYT?

[chalin]

Thinking about this more ... The OTel website has enough complexity already, that I'd avoid introducing the overhead of having to maintain subdomains like php.api.opentelemetry.io for each language.

[svrnm]

The OTel website has enough complexity already,

This would be an independent netlify site, so not getting into the otel website itself except introducing redirects.

that I'd avoid introducing the overhead of having to maintain subdomains like php.api.opentelemetry.io for each language.

So you would rather have it the SIG PHP hosted themselves using github pages / read the docs, like other languages are doing it?

[chalin]

Sorry for the confusion: my comment wasn't about hosting on Netlify (which I'm ok with), it was about not introducing the <lang>.api.otel.io subdomains.

[svrnm]

Sorry for the confusion: my comment wasn't about hosting on Netlify (which I'm ok with), it was about not introducing the <lang>.api.otel.io subdomains.

The subdomain would only be introduced for those languages that are hosted on netlify, because that looks better than https://main--opentelemetry-php.netlify.app/, except we only do the rewrite with proxy and have it under opentelemetry.io/path/to/it/php, although in that case I would prefer to have it outside the existing tree (i.e. /docs/languages/php/api), since we already see that this may lead to issues as in #5211, so opentelemetry.io/api/php might be a safer choice imho

[chalin]

This can be closed, right @svrnm?