Rendering API references improvements

[cartermp]

Howdy! We're looking to link directly to https://open-telemetry.github.io/opentelemetry-js/ on the website (open-telemetry/opentelemetry.io#1936) since it's the closest thing to an "API docs hub" that we have for JS. However, it's a little noisy since it's also got a rendering of the main README for this repo as the home page.

Ideally, we'd like to something like what Java has here: https://javadoc.io/doc/io.opentelemetry - this style makes it easy to navigate to the particular API reference that you need when you're in the thick of things with a specific API.

Is this accomplishable with the current system for generating API references? Would be happy to take this one on myself, but don't really know where to begin or if this is something y'all would like to have.

[legendecas]

https://open-telemetry.github.io/opentelemetry-js/ and https://open-telemetry.github.io/opentelemetry-js-api/ are the rendered API references for JavaScript packages (the latter one is going to be merged into the first one, as their repos are merged).

We are generating the API reference with typedoc. The scripts can be found at: https://github.com/open-telemetry/opentelemetry-js/blob/main/.github/workflows/docs.yaml

[dyladan]

There are a couple things we could do

• Use --readme none to make the modules page the default landing page
• Generate a readme from the lerna module listing
• Update the readme (something we really should do anyway) and make it a better landing page

[dyladan]

The https://open-telemetry.github.io/opentelemetry-js-api/ page will be removed as that repo is being deprecated and archived. All api/sdk packages will live in this repo

[dyladan]

@chalin i see your +1 but do you have a particular preference which of the 3 options we do? (3) should really be done no matter what IMO but (1) or (2) can also be done at the same time.

[chalin]

The https://open-telemetry.github.io/opentelemetry-js-api/ page will be removed as that repo is being deprecated and archived. All api/sdk packages will live in this repo

Thanks for the background info and confirmation that the URL we're using now as a API-reference target is the good one.

do you have a particular preference which of the 3 options we do? (3) should really be done no matter what IMO but (1) or (2) can also be done at the same time.

I don't have a strong preference. Whatever you feel can be implemented either quickly and/or serve well your dev clientele.
(3) seemed like the "obvious" option for me. I don't know what the other two options would look like, so ultimately, it's your call. (Of course y'all can try one option or another and change your mind too if you feel something better would serve the API-ref readers.)

[cartermp]

With #3369 I think this is more or less resolved. It could get improved to look at a lot better, but it does exactly what it needs to do --> lists the API reference per-package and lets you dig into stuff. I'll close this issue and if we get feedback about improving the visual rendering/IA we can take it from there.