[editorial] Problems publishing v1.37.0+ to the OTel.io website

[chalin]

Area(s)

docs

What's the problem?

The OTel.io website build is failing for semconv v1.37.0. For details, see:

• Update semantic-conventions version to v1.37.0 opentelemetry.io#7638 (review)

Detailed list of problems

• New JSON schema files are now contained in various spec folders. This is a new feature that the OTel.io website will need to adapt to. See comments further below for a discussion about how we want to resolve this.
• New non-normative subfolders were introduced, e.g., https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai/non-normative. In the past, all non-normative pages were put under https://github.com/open-telemetry/semantic-conventions/tree/main/docs/non-normative. We'll need to discuss how to recover from this.
• The hash target /docs/general/metrics/#metric-requirement-levels, used in many places, doesn't exist. @trask any idea why the link check didn't pick up on this? For example, visit https://github.com/open-telemetry/semantic-conventions/blob/main/docs/hardware/gpu.md#metric-hwgpuio, and click on the recommended link. It visits the page, but the hash target doesn't exist.
  • I think that the use of that invalid link should be replaced by https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md#recommended.
    [Update]: fix - Fix metrics requirement level link #2691
• Inline images are not being rendered correctly (they would technically need to be marked .img-initial). For context, see [chore] Clean up Entity snippets - make sure they include identifying vs. descriptive roles #2970 (comment), or just see the badge images in https://opentelemetry.io/docs/specs/semconv/registry/entities/browser/, for example. See [semconv] Badges aren't being displayed properly opentelemetry.io#8288

Describe the solution you'd like

TBC

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

/cc @lmolkova @open-telemetry/docs-maintainers

[chalin]

Originally posted by @lmolkova in open-telemetry/opentelemetry.io#7638 (comment):

it seems internal links to internal json files are a problem - the link to json is rewritten, but json file itself is not published. It makes sense to use absolute url to github for these.

Yes, the JSON files are causing problems.

Anything special we can do on the semconv side going forward in cases like this?

I need to better understand the role of these JSON files. Are the JSON files normative or are they only given as examples?

[chalin]

@lmolkova - looking at the relevant pages of the spec, it seems that the JSON files are schemas. I guess that we'd want these published on the OTel.io website too?

[chalin]

@trask - the link checker seems to have missed /docs/general/metrics.md#metric-requirement-levels as an invalid link hash target. Any idea why?

[chalin]

/cc @vitorvasc @theletterf @tiffany76 so you can follow the details of the issue with the semconv PR.

[chalin]

@lmolkova et all: I think that the use of the /docs/general/metrics/#metric-requirement-levels invalid link should be replaced by https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md#recommended. Can you confirm?

To be clear, the markdown link definitions of the form:

[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels

should be

[MetricRecommended]: /docs/general/attribute-requirement-level.md#recommended

WDYT?

[chalin]

With the goal of not delaying the publication of the 1.37.0 spec, I've applied some patches, so that the PR now builds, see:

• Update semantic-conventions version to v1.37.0 opentelemetry.io#7638 (comment)

The two patches are:

• I assume that [MetricRecommended]: /docs/general/attribute-requirement-level.md#recommended is the correct link. For details, see [editorial] Problems publishing v1.37.0+ to the OTel.io website #2690 (comment)
• Schema .json and Jupyter Notebook files (.ipynb) are published to the website too. This isn't ideal since, for example, we don't have a previewer for Jupyter Notebook files, but GitHub provides one.

Let me know if these temporary patches are good enough for now.

Note that we still need to discuss whether there should be a single top-level non-normative folder, or whether spec authors are permitted to sprinkle non-normtave subfolders throughout the specification directory.

[lmolkova]

thanks @chalin !

I'm fixing metrics links in #2691 - will check why we let it in in a sec.

Schema .json and Jupyter Notebook files (.ipynb) are published to the website too. This isn't ideal since, for example, we don't have a previewer for Jupyter Notebook files, but GitHub provides

Left a comment on this in the open-telemetry/opentelemetry.io#7638 (comment)

I'd be more than happy to define some conventions and checks that won't require manual patches on otel.io for things like this. E.g. we can prefix files names in a certain way, or do something else, but I think it's important for semconv authors to include json/yaml/code/pictures/diagrams/examples and non-normative things in arbitrary files next to the main content. E.g. having genai-related content spread across the repo to optimize for otel.io does not seem ideal either.