Add SemConv spec under docs/specs (preview)

[chalin]

• Contributes to Adjust to move Semantic Conventions out of OTel spec #2721
• Supersedes Fixes #2907 - Schema files are served from semantic-conventions. #2908
• Adds semconv spec to docs/specs
• Pages will only appear in deploy previews, not on the production server, since all spec pages are marked as draft: true
• We won't want to publish the semconv spec until the following restructuring is complete, IMHO:
  Feature Request: Restructure Semantic Convention markdown to be topical vs. by signal semantic-conventions#137

Preview: https://deploy-preview-2920--opentelemetry.netlify.app/docs/specs/semconv/

/cc @jsuereth @joaopgrassi

[chalin]

Thanks for the review @cartermp! Will wait for feedback from @jsuereth and @joaopgrassi.

[cartermp]

Yep, figured as much

[joaopgrassi]

Looks good to me, given things will change after #137.

One question though: Do you think the structure defined here open-telemetry/semantic-conventions#137 (comment) is possible to reproduce on the website? Or: Does it even make sense to you?

[jsuereth]

We're going through a refactoring of the semantic conventions markdown right now.

Can we just mount tmp/semconv/specification? There will be a top-level readme file there shortly and I'm happy to give it all the hugo content you need.

We do not want to have logs/metrics/trace specific locations going forward.

[chalin]

I've answered further below.

[chalin]

Do you think the structure defined here open-telemetry/semantic-conventions#137 (comment) is possible to reproduce on the website?

@joaopgrassi - yes, it will actually be easier to bring in. This is just a preview of what it would look like under the current organization.

We're going through a refactoring of the semantic conventions markdown right now.

Can we just mount tmp/semconv/specification? There will be a top-level readme file there shortly and I'm happy to give it all the hugo content you need.

We do not want to have logs/metrics/trace specific locations going forward.

@jsuereth - right, this PR is just in preparation, while open-telemetry/semantic-conventions#137 is being addressed.

I'd you agree (and approve this PR @jsuereth), I'd like to merge this PR As I mentioned earlier, the semconv spec will not show up in production. As work progresses on in the semconv repo, I can submit followup PRs.

[chalin]

@jsuereth @joaopgrassi - btw, regarding the linkTitle, which only shows up in the sidenav: the reason I chose SemConv as a side-nav title is so we can avoid word-wrap (as you can see below), and because it is more consistent with the other specs. If we use the full name "Semantic Conventions", plus the version, it's a bit too wide IMHO:

It's a detail, not very important, but I wanted to at least explain why so that you can make a more informed choice of what you'd like the linkTitle to be.

[jsuereth]

FYI - This relates to the previous PR in this chain, but something we should fix ASAP: open-telemetry/opentelemetry-specification#3572

[joaopgrassi]

btw, regarding the linkTitle, which only shows up in the sidenav: the reason I chose SemConv as a side-nav title is so we can avoid word-wrap (as you can see below), and because it is more consistent with the other specs. If we use the full name "Semantic Conventions", plus the version, it's a bit too wide IMHO:

I see. I think the word wrap isn't great, but I think I prefer that over the "cryptic" SemConv one. But even in my 1080p monitor there was no wrap, so should be OK? I guess if it comes to that, we can do some css magic :D

[joaopgrassi]

Also: We will be listing under "Semantic Conventions" just the "latest version" right? We will not have something like

Semantic Conventions
- 1.22.0
- 1.23.0
...

[chalin]

@joaopgrassi - correct, only the latest officially released version (at least, that is what we're doing with the OTel spec, and we can do the same here).

[chalin]

@jsuereth - so, is this preview PR good to go?

[jsuereth]

Under the caveat that we'll change the import going forward for new layout, yeah, let's keep making steady progress.

I do have a few question for follow up PRs:

• How do we get left-hand outline like the spec has for sections?
• Can we change all links to specification in semconv to point at the otel.io copy of the specification?
• Can we change all links to semconv from the specification to point at the otel.io copy of the semconv?

For the last two I was working on the perl script to make this happen.

[chalin]

@jsuereth - I've answered in #2721 (comment).