Opentelemetry-js: Host API Documentation

[mayurkale22]

Per SIG meeting, decide where to host the generated docs (npm run docs or yarn docs). Also, decide when to update the same, either on every new release or every pull requests merge.

Few hosting options:

• Github pages

• Some external domain similar to opentracing - https://opentracing-javascript.surge.sh/

/cc @danielkhan

[OlivierAlbertini]

How do you manage multiple versions (1.0.0, 2.0.0...) when packages will be released for production ? Do we display only the last ?

[mayurkale22]

How do you manage multiple versions (1.0.0, 2.0.0...) when packages will be released for production ? Do we display only the last ?

I think always display the latest one and with the help of CHANGELOG users will be able to see when it got added. Another option is to use @version tag with newly added API, but I am not sure whether it is supported with typedoc.

[draffensperger]

Can we use GitHub pages with this repo to start with and then potentially move to a hosted domain? I think GitHub pages supports custom domains

[OlivierAlbertini]

How do you manage multiple versions (1.0.0, 2.0.0...) when packages will be released for production ? Do we display only the last ?

I think always display the latest one and with the help of CHANGELOG users will be able to see when it got added. Another option is to use @version tag with newly added API, but I am not sure whether it is supported with typedoc.

a solution : https://github.com/TypeStrong/typedoc/issues/737#issuecomment-439382488

[dyladan]

If we want to host in GitHub Pages, here is how we can do it using circle ci to update docs each time master is built https://github.com/dyladan/opentelemetry-js/tree/ci-docs

Output looks like this https://dyladan.github.io/opentelemetry-js/

This is the change I made to make it work https://github.com/dyladan/opentelemetry-js/commit/f5be3d89f33e4ce08659a6f0e988c1e05f871b0d

Right now the ssh key fingerprint is for my fork, but if we want to do it we just need a deploy key created and I can make the PR.

[mayurkale22]

This looks really good 💯 IMO we should update the API docs on every release (post release script) rather than each time master is built. Otherwise users would see un-released features/APIs in the docs, that might lead to confusions and all. On top of that, the API update happens once in a while. WDYT?

[dyladan]

Yea I agree that it should happen on release. Is there some way to automate that? I don't know what our current release mechanism is, but if it adds a tag that could be used as a filter. We could also keep a branch named release or latest or similar.

edit: it looks like the current release created and pushed a tag v0.1.0 to GitHub. We could filter the deploy docs on tags that match ^v\d+\.\d+\.\d+$ if that tag is guaranteed by the current process

edit 2: looks like the current release is actually 0.1.1 not 0.1.0 so whatever the current process is does _not_ guarantee a tag in GitHub. Maybe we should automate the whole release process?

[dyladan]

Additional note: Since the @opentelemetry/types is going to be the "official" public documentation for the API, we should change its README to reflect that. Currently the title is "OpenTelemetry Types" which should probably be changed to "OpenTelemetry API". Additionally, some quick usage examples could be added there. I'm working on a getting started guide for #416 that would be a good idea to at least link to if not include right in the README

[mayurkale22]

Additional note: Since the @opentelemetry/types is going to be the "official" public documentation for the API, we should change its README to reflect that. Currently the title is "OpenTelemetry Types" which should probably be changed to "OpenTelemetry API".

Sounds good to me. May be "OpenTelemetry API for JavaScript"

Additionally, some quick usage examples could be added there. I'm working on a getting started guide for #416 that would be a good idea to at least link to if not include right in the README

https://github.com/open-telemetry/opentelemetry-js/blob/91fd682b8607b61fb1696ebd65b27eca32b66a95/packages/opentelemetry-types/src/trace/tracer.ts#L52-L53 Do you mean something like this?

[dyladan]

No I just mean more end-to-end examples. The getting started guide will focus on how can I set up a tracing backend and use auto instrumentation to get traces, but there are additional use cases that should be covered. How can a library author add OpenTelemetry support and so on.

The docs are currently useful from a "how do I call this method?" standpoint, but leave something to be desired in terms of "why do I call this method?"

[dyladan]

Updated it so that it only runs on semver style git tags (v0.0.0) and no other branches https://github.com/dyladan/opentelemetry-js/blob/a0bd6bb2820c180ffe79d522d3fab540cfe195b0/.circleci/config.yml#L123

One issue is that this depends on the git tag being created, which is not always the case currently (e.g. current release has no tag). Maybe we should talk about release automation in general at the SIG meeting

[dyladan]

Can someone assign this to me? I'll make a PR based on the tag triggered version Monday.

[mayurkale22]

Can someone assign this to me? I'll make a PR based on the tag triggered version Monday.

Done.