Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use render-link hook to resolve references in specs #6032

Merged
merged 1 commit into from
Jan 22, 2025
Merged

Use render-link hook to resolve references in specs #6032

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions content/en/docs/specs/status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ same as the **Protocol** status.
- [Specification][tracing]
- {{% spec_status "API" "otel/trace/api" "Status" %}}
- {{% spec_status "SDK" "otel/trace/sdk" "Status" %}}
- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*trace" %}}
- {{% spec_status "Protocol" "otlp" "/document-status.*for.*trace" %}}
- Notes:
- The tracing specification is now completely stable, and covered by long term
support.
Expand All @@ -73,7 +73,7 @@ same as the **Protocol** status.
- [Specification][metrics]
- {{% spec_status "API" "otel/metrics/api" "Status" %}}
- {{% spec_status "SDK" "otel/metrics/sdk" "Status" %}}
- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*metric" %}}
- {{% spec_status "Protocol" "otlp" "/document-status.*for.*metric" %}}
- Notes:
- OpenTelemetry Metrics is currently under active development.
- The data model is stable and released as part of the OTLP protocol.
Expand All @@ -98,7 +98,7 @@ same as the **Protocol** status.
- [Specification][logging]
- {{% spec_status "Bridge API" "otel/logs/api" "Status" %}}
- {{% spec_status "SDK" "otel/logs/sdk" "Status" %}}
- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*log" %}}
- {{% spec_status "Protocol" "otlp" "/document-status.*for.*log" %}}
- Notes:
- The [logs data model][] is released as part of the OpenTelemetry Protocol.
- Log processing for many data formats has been added to the Collector, thanks
Expand All @@ -116,7 +116,7 @@ same as the **Protocol** status.
### Profiles

- [Specification][profiles]
- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*profiles" %}}
- {{% spec_status "Protocol" "otlp" "/document-status.*for.*profiles" %}}

[baggage]: /docs/specs/otel/baggage/
[event semantic conventions]: /docs/specs/semconv/general/events/
Expand Down
29 changes: 26 additions & 3 deletions layouts/_default/_markup/render-link.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
{{ $url := .Destination -}}
{{ $url := .Destination -}} {{/* TODO: rename to $dest */ -}}
{{ $u := urls.Parse $url -}}

{{/*

Expand All @@ -10,9 +11,32 @@
- $url is an absolute path -- that is, it starts with /
- The $url target page exists in this locale

Reference to Hugo's default:
https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-link.html

*/ -}}

{{ if hasPrefix $url "/" -}}

{{ if and
(strings.HasPrefix $.PageInner.RelPermalink "/docs/specs")
(not $u.IsAbs)
(not (strings.HasPrefix $url "#"))
-}}
{{ $path := replaceRE `\bREADME\.md\b` "_index.md" $u.Path -}}
{{ $href := $url -}}
{{ with or
($.PageInner.GetPage $path)
($.PageInner.Resources.Get $path)
(resources.Get $path)
-}}
{{ $href = .RelPermalink -}}
{{ with $u.RawQuery -}}{{ $href = printf "%s?%s" $href . -}}{{ end -}}
{{ with $u.Fragment -}}{{ $href = printf "%s#%s" $href . -}}{{ end -}}
{{ else -}}
{{ warnf "File %s: cannot resolve spec link reference '%s'" .Page.File.Filename $url -}}
{{ end -}}
{{ $url = $href -}}
{{ else if hasPrefix $url "/" -}}
{{/* Hard-coded default lang since it's what's most efficient and won't change :) */ -}}
{{ $defaultLang := "en" -}}
{{ $lang := .Page.Language.Lang -}}
Expand All @@ -22,7 +46,6 @@
{{ warnf "File %s: drop unnecessary '%s' prefix from %s"
.Page.File.Filename $langPathPrefix $url -}}
{{ else -}}
{{ $u := urls.Parse $url -}}
{{ $localizedPagePath := add $langPathPrefix (strings.TrimPrefix "/" $url) -}}
{{/*
Look for the page (referenced by $url) in this page's locale's site.
Expand Down
91 changes: 2 additions & 89 deletions scripts/content-modules/adjust-pages.pl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@
my $otlpSpecVers = $versions{'otlp:'};
my $semconvVers = $versions{'semconv:'};
my %patchMsgCount;
my $openRelref = '{{% relref';

sub printTitleAndFrontMatter() {
print "---\n";
Expand Down Expand Up @@ -119,7 +118,7 @@ ($$)

## Semconv

if ($ARGV =~ /\/semconv/) {
if ($ARGV =~ /^tmp\/semconv/) {
my $otel_spec_event_deprecation = '(opentelemetry-specification/blob/main/specification/logs)/event-(api|sdk).md';
if (/$otel_spec_event_deprecation/) {
# Cf. https://github.com/open-telemetry/opentelemetry-specification/pull/4359
Expand All @@ -131,13 +130,6 @@ ($$)
s|(\]:\s*)/docs/|$1$specBasePath/semconv/|;

s|\((/model/.*?)\)|($semconvSpecRepoUrl/tree/v$semconvVers/$1)|g;

# TODO: drop after fix of https://github.com/open-telemetry/semantic-conventions/pull/1316
s|#instrument-advice\b|#instrument-advisory-parameters|g;

# TODO: drop after fix of https://github.com/open-telemetry/semantic-conventions/issues/1313
s|(/database/database-spans\.md)#batch-operations|$1|g;
s|(/messaging/messaging-spans\.md)#common-messaging-operations|$1|g;
}


Expand All @@ -153,7 +145,6 @@ ($$)

s|\(https://github.com/open-telemetry/opentelemetry-specification\)|($specBasePath/otel/)|;
s|(\]\()/specification/|$1$specBasePath/otel/)|;
s|\.\./semantic_conventions/README.md|$semConvRef| if $ARGV =~ /overview/;
s|\.\./specification/(.*?\))|../otel/$1|g if $ARGV =~ /otel\/specification/;

# Match markdown inline links or link definitions to OTel spec pages: "[...](URL)" or "[...]: URL"
Expand All @@ -172,93 +163,15 @@ ($$)
s|(\]\()([^)]+\.png\))|$1../$2|g if $ARGV =~ /\btmp\/semconv\/docs\/general\/attributes/;
s|(\]\()([^)]+\.png\))|$1../$2|g if $ARGV =~ /\btmp\/semconv\/docs\/http\/http-spans/;

# Handle links containing `README.md`

# Rewrite paths that are outside of the spec folders as external links:

s|\.\.\/README.md|$otelSpecRepoUrl/|g if $ARGV =~ /specification._index/;
s|\.\.\/README.md|..| if $ARGV =~ /specification\/library-guidelines.md/;
s|\.\.\/README.md|/docs/specs/otel/| if $ARGV =~ /specification\/library-guidelines.md/;

s|(\.\.\/)+(experimental\/[^)]+)|$otelSpecRepoUrl/tree/v$otelSpecVers/$2|g;
s|(\.\.\/)+(supplementary-guidelines\/compatibility\/[^)]+)|$otelSpecRepoUrl/tree/v$otelSpecVers/$2|g;

s|\.\./((?:examples/)?README\.md)|$otlpSpecRepoUrl/tree/v$otlpSpecVers/$1|g if $ARGV =~ /^tmp\/otlp/;

# Replace `README.md` by `_index.md` in markdown links:
s{
# An inline markdown link, just before the URL: `](` like in `[docs](/docs)`
(
\]\(
)

# Match any local path. In the `[^...]` exclude group we have:
# - `:` so as to exclude external links, which use `:` after a protocol specifier
# - `)` prevents us from gobbling up past the end of the inline link

([^:\)]*)
README\.md
([^)]*) # Any anchor specifier
(\)) # The end of the inline link
}{$1$openRelref "$2_index.md$3" \%\}\}$4}gx;

# Replace `README.md` by `_index.md` in markdown link definitions:
s{
# A markdown link definition, just before the URL: `]:`, like in `[docs]: /docs`
(
\]:\s*
)

# Match any local path. In the `[^...]` exclude group we have:
# - `:` so as to exclude external links, which use `:` after a protocol specifier
# - A space should prevent us from gobbling up beyond the end of a link def

([^: ]*)
README\.md
([^)]*) # Any anchor specifier
(\n)$ # End of the link definition
}{$1$openRelref "$2_index.md$3" \%\}\}$4}gx;

# Rewrite inline links
if ($ARGV =~ /\btmp\/opamp/) {
s|\]\(([^:\)]*?)\.md((#.*?)?)\)|]($1/$2)|g;
} else {
# Generally rewrite markdown links as {{% relref "..." %}} expressions,
# since that gets Hugo to resolve the links. We can't use the raw path since
# some need a `../` prefix to resolve. We let Hugo handle that.
s{
# Match markdown link `](` just before the URL
(\]\()

# Match the link path:
(
# Match paths upto but excluding `.md`. The character exclusions are as follows:
#
# - `:` ensures the URL is a path, not an external link, which has a protocol followe by `:`
# - `)` so we don't overrun the end of the markdown link, which ends with `)`
# - `{` or `}` so that the path doesn't contain Hugo {{...}}

[^:\)\{\}]*?

\.md

# Match optional anchor of the form `#some-id`
(?:
\#.*?
)?
)
# Closing parenthesis of markdown link
\)
}{$1$openRelref "$2" \%\}\}\)}gx;
}

# Rewrite link defs to local pages such as the following:
#
# [specification]: overview.md
# [faas]: some-path/faas-spans.md (FaaS trace conventions)
#
# The subregex `[:\s]+` excludes external URLs (because they contain a colon after the protocol)
s|^(\[[^\]]+\]:\s*)([^:\s]+)(\s*(\(.*\))?)$|$1\{{% relref "$2" %}}$3|g;

# Make website-local page references local:
s|https://opentelemetry.io/|/|g;

Expand Down
Loading