docs: merge package api docs

[legendecas]

Which problem is this PR solving?

Merge api/docs into root doc directory.

Type of change

• This change requires a documentation update

Checklist:

• Followed the style guidelines of this project
• Documentation has been updated

[codecov]

Codecov Report

Merging #3255 (7aacd2c) into main (1864a9a) will decrease coverage by 0.38%.
The diff coverage is n/a.

❗ Current head 7aacd2c differs from pull request most recent head 7ae1b26. Consider uploading reports for the commit 7ae1b26 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3255      +/-   ##
==========================================
- Coverage   93.42%   93.03%   -0.39%     
==========================================
  Files         241      226      -15     
  Lines        7253     6517     -736     
  Branches     1507     1360     -147     
==========================================
- Hits         6776     6063     -713     
+ Misses        477      454      -23     

Impacted Files	Coverage Δ
api/karma.worker.js	0.00% <0.00%> (-100.00%)	⬇️
packages/opentelemetry-resources/karma.worker.js	0.00% <0.00%> (-100.00%)	⬇️
...kages/opentelemetry-sdk-trace-base/karma.worker.js	0.00% <0.00%> (-100.00%)	⬇️
...lemetry-resources/src/detectors/BrowserDetector.ts	53.33% <0.00%> (-46.67%)	⬇️
...lemetry-resources/src/detectors/ProcessDetector.ts	95.45% <0.00%> (-4.55%)	⬇️
...ntelemetry-resources/src/detectors/NoopDetector.ts
...entelemetry-sdk-trace-web/src/WebTracerProvider.ts
...es/opentelemetry-context-zone-peer-dep/src/util.ts
...ckages/opentelemetry-sdk-trace-web/karma.worker.js
...emetry-instrumentation-xml-http-request/src/xhr.ts
... and 10 more

[dyladan]

These docs are actually on the website I believe already. They shouldn't be maintained in 2 places. Maybe we can replace the website version with a submodule if we want to maintain them here?

[legendecas]

Are there any suggestions on maintaining language-sdk documentation? Should we move all our documents to the website repository?

I don't have a strong opinion on this. I agree that we should maintain the documents in one place.

[vmarchaud]

I can't find a place where SDK documentation is on the website, maybe @svrnm or @cartermp can help ?

[cartermp]

When you say "language-sdk", who is the intended audience? If it is otel developer docs (e.g., extenders of otel-js) then I think it's fine to keep and maintain here. But if it's end-user docs then it should just live in the website repo. The end-user docs are actively maintained and organized based on working with end users.

[dyladan]

@cartermp the sdk docs he's referring to are the reference docs generated from annotations/comments in the source code. Currently they're published on github.io (https://open-telemetry.github.io/opentelemetry-js/) on each release automatically. The intended audience is typically an SDK end user but they are more of a reference material than how-to docs or anything like that and there is very little editorial work to be done.

[cartermp]

Aha, makes sense! Yeah, those shouldn't be hosted on the website.

There may be some interesting future wherein we figure out a good way to represent language API reference docs and explore what website hosting look like, but given that each language has different ways to generate API docs, and developers from those languages will likely expect the format for that generator, and there's 11 languages to worry about ... for the foreseeable future, the website won't do anything other than link to API reference docs.

[svrnm]

Aha, makes sense! Yeah, those shouldn't be hosted on the website.

+1, yes, for now we have to keep them off the website unfortunately. But we should have a link to them, or even a page that says "API & SDK Docs" or whatever and then point to that external page

There may be some interesting future wherein we figure out a good way to represent language API reference docs and explore what website hosting look like, but given that each language has different ways to generate API docs, and developers from those languages will likely expect the format for that generator, and there's 11 languages to worry about ... for the foreseeable future, the website won't do anything other than link to API reference docs.

I am wondering if we at least could house them within opentelemetry.io? Like opentelemetry.io/js-docs/ points to https://open-telemetry.github.io/opentelemetry-js/ and opentelemetry/java-docs/ points to the java docs, etc?

[dyladan]

given that each language has different ways to generate API docs, and developers from those languages will likely expect the format for that generator, and there's 11 languages to worry about ... for the foreseeable future, the website won't do anything other than link to API reference docs.

I think this makes sense. Linking to it is an easy win though.

I am wondering if we at least could house them within opentelemetry.io? Like opentelemetry.io/js-docs/ points to https://open-telemetry.github.io/opentelemetry-js/ and opentelemetry/java-docs/ points to the java docs, etc?

Honestly we don't really even need them hosted on github.io. They could easily be hosted on the main website as long as they're in the expected format.

[dyladan]

The browser and webworker test failures seem probably unrelated?

[cartermp]

I created open-telemetry/opentelemetry.io#1808 based on discussion here. No pressing need to engage, but for now we do link to the API reference and will see if there's a way to make it a little more prominent.

[legendecas]

The browser and webworker test failures seem probably unrelated?

@dyladan no idea why the repo failed to be checkout in web and worker tests. 😕 restarting.

[legendecas]

Thank you all for the clarification. I agree that hosting and maintaining end-user documentation on the website, and SDK documentation in the languages' own repo is a good idea.