From c81613f13a50a8a813bc0d9f239c60800051570a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 22 Jan 2025 13:35:48 -0500 Subject: [PATCH] Use render-link hook to resolve references in specs (#6032) --- content/en/docs/specs/status.md | 8 +- layouts/_default/_markup/render-link.html | 29 +++++++- scripts/content-modules/adjust-pages.pl | 91 +---------------------- 3 files changed, 32 insertions(+), 96 deletions(-) diff --git a/content/en/docs/specs/status.md b/content/en/docs/specs/status.md index 3873cadeb6c9..a6edac91a1d9 100644 --- a/content/en/docs/specs/status.md +++ b/content/en/docs/specs/status.md @@ -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. @@ -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. @@ -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 @@ -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/ diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index 0a9640362619..da9acb612e3a 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -1,4 +1,5 @@ -{{ $url := .Destination -}} +{{ $url := .Destination -}} {{/* TODO: rename to $dest */ -}} +{{ $u := urls.Parse $url -}} {{/* @@ -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 -}} @@ -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. diff --git a/scripts/content-modules/adjust-pages.pl b/scripts/content-modules/adjust-pages.pl index 15cdb8f02255..68a763153670 100755 --- a/scripts/content-modules/adjust-pages.pl +++ b/scripts/content-modules/adjust-pages.pl @@ -26,7 +26,6 @@ my $otlpSpecVers = $versions{'otlp:'}; my $semconvVers = $versions{'semconv:'}; my %patchMsgCount; -my $openRelref = '{{% relref'; sub printTitleAndFrontMatter() { print "---\n"; @@ -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 @@ -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; } @@ -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" @@ -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;