From 707c1def9a886d89664f5599574b1f7b4ad68000 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 14 Nov 2023 05:44:12 -0500 Subject: [PATCH] Schemas at `/schemas` in YAML, and `/schemas/list` in HTML --- .htmltest.yml | 1 + assets/scss/_schema.scss | 22 ++++++++++++++++++++++ assets/scss/_styles_project.scss | 1 + content/en/schemas/_index.md | 25 +++++++++++++++++++++++++ content/en/schemas/list.md | 21 +++++++++++++++++++++ hugo.yaml | 7 +++++-- layouts/index.redirects | 3 +++ layouts/schemas/section.yaml | 10 ++++++++++ layouts/shortcodes/schemas.md | 10 ++++++++++ netlify.toml | 24 +++++++++++++++++++++++- 10 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 assets/scss/_schema.scss create mode 100644 content/en/schemas/_index.md create mode 100644 content/en/schemas/list.md create mode 100644 layouts/schemas/section.yaml create mode 100644 layouts/shortcodes/schemas.md diff --git a/.htmltest.yml b/.htmltest.yml index d29cf03b3de6..7dc8186eea4e 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -5,6 +5,7 @@ IgnoreAltMissing: true IgnoreCanonicalBrokenLinks: false CheckMailto: false IgnoreInternalURLs: # list of paths + - /schemas/latest IgnoreURLs: # list of regexs of paths or URLs to be ignored - ^/docs/instrumentation/\w+/(api|examples)/$ - ^/docs/instrumentation/net/(metrics-api|traces-api)/ diff --git a/assets/scss/_schema.scss b/assets/scss/_schema.scss new file mode 100644 index 000000000000..de92bb0e46df --- /dev/null +++ b/assets/scss/_schema.scss @@ -0,0 +1,22 @@ +.ot-schema-list, +.ot-schemas-404 { + // Hide the sidebar. Add the sidebar's number of col to `main` + main { + @extend .col-md-10; + } + + .td-sidebar { + display: none; + } + + main td code { + background-color: inherit; + } + + // Fixes https://github.com/open-telemetry/opentelemetry.io/issues/1102 + // TODO: upstream + .td-sidebar-toc { + margin-top: 4rem; + top: 0; + } +} diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 1c24d74c3b11..25e213969966 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -4,6 +4,7 @@ @import 'registry'; @import 'tabs'; @import 'external_link'; +@import 'schema'; .td-home { .otel-logo { diff --git a/content/en/schemas/_index.md b/content/en/schemas/_index.md new file mode 100644 index 000000000000..fab611c19c9d --- /dev/null +++ b/content/en/schemas/_index.md @@ -0,0 +1,25 @@ +--- +title: 404 - Schema not found +linkTitle: Schemas +type: docs +no_list: true +body_class: ot-schemas-404 +outputs: [HTML, YAML] +# +# Note: +# The paths to the `list` and `latest` are absolute below since we +# don't know from which URL this 404 page will be served. +# +--- + +The page or schema you requested doesn't exist. Maybe you're looking for one of +these: + +- [List of schemas](/schemas/list/) hosted on this site, also available in + [YAML format](/schemas/index.yaml) +- [Latest](/schemas/latest) schema +- More information about [Telemetry Schemas] in general, or [OpenTelemetry + Schema] in particular. + +[OpenTelemetry Schema]: /docs/specs/otel/schemas/#opentelemetry-schema +[Telemetry Schemas]: /docs/specs/otel/schemas/ diff --git a/content/en/schemas/list.md b/content/en/schemas/list.md new file mode 100644 index 000000000000..d616e9219669 --- /dev/null +++ b/content/en/schemas/list.md @@ -0,0 +1,21 @@ +--- +title: OpenTelemetry Schemas +linkTitle: List +type: docs +body_class: ot-schema-list +--- + +{{% alert title=" Warning" color="warning" %}} + +This page, its content, and formatting are **non-normative** and **subject to +change**. In particular it is not meant for automated processing. + +{{% /alert %}} + +The OpenTelemetry schemas hosted on this site are listed below. To learn more +about schemas, see [Telemetry Schemas][]. The list is also available in +[YAML format](/schemas/index.yaml). + +{{% schemas %}} + +[Telemetry Schemas]: /docs/specs/otel/schemas/ diff --git a/hugo.yaml b/hugo.yaml index 6cfa3adac621..76c062c26357 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -32,15 +32,18 @@ markup: # noClasses: false style: tango -# Netlify _redirects file mediaTypes: - text/netlify: {} + text/netlify: {} # Netlify _redirects file + text/yaml: {} outputFormats: REDIRECTS: mediaType: text/netlify baseName: _redirects notAlternative: true + YAML: # Yaml for Schemas index page + mediaType: text/yaml + baseName: index.yaml outputs: home: [HTML, REDIRECTS, RSS] diff --git a/layouts/index.redirects b/layouts/index.redirects index 280f6762074b..20a936e3ac9b 100644 --- a/layouts/index.redirects +++ b/layouts/index.redirects @@ -47,7 +47,10 @@ {{ $schemaFiles := partial "schema-file-list" . -}} {{ $latestSchemaFile := index $schemaFiles 0 -}} +/schemas /schemas/index.yaml /schemas/latest /schemas/{{ $latestSchemaFile.Name }} +/schemas/list /schemas/list/ 200 # Explicit rule to avoid the next catch all +/schemas/* /schemas/? 404 # Report 404 for anything else that's missing {{/* Social-media image redirects. As mentioned in diff --git a/layouts/schemas/section.yaml b/layouts/schemas/section.yaml new file mode 100644 index 000000000000..3e9d2652509c --- /dev/null +++ b/layouts/schemas/section.yaml @@ -0,0 +1,10 @@ +{{ $schemaFiles := partial "schema-file-list" . -}} +{{ $latestSchemaFile := index $schemaFiles 0 -}} +# OpenTelemetry Schemas +# +# https://github.com/open-telemetry/semantic-conventions/tree/v{{ $latestSchemaFile.Name }}/schemas +# +{{ $schemaFiles := partial "schema-file-list.html" . -}} +{{- range $schemaFiles -}} +- {{ .Name }} +{{ end -}} diff --git a/layouts/shortcodes/schemas.md b/layouts/shortcodes/schemas.md new file mode 100644 index 000000000000..88e08584533c --- /dev/null +++ b/layouts/shortcodes/schemas.md @@ -0,0 +1,10 @@ +{{- $schemaFiles := partial "schema-file-list.html" . -}} + +| Version | +|---------| +{{ range $i, $schema := $schemaFiles -}} +| [`{{ $schema.Name }}`](/schemas/{{ $schema.Name }}) +{{- if eq $i 0 -}} + ([latest](/schemas/latest)) +{{- end -}} | +{{ end -}} diff --git a/netlify.toml b/netlify.toml index e40a456e069c..0b00b0c5b97d 100644 --- a/netlify.toml +++ b/netlify.toml @@ -15,7 +15,29 @@ from = "https://blog.opentelemetry.io/*" to = "https://opentelemetry.io/blog/:splat" force = true +# Schemas + +[[headers]] + for = "/schemas/" + [headers.values] + content-type = "text/yaml" + +# Ensure that there is a header entry for each major version of the published +# schemas. (If this becomes too bothersome to update, we can automate the +# creation of these schema header entries in a `_headers` file using Hugo +# templating constructs.) + +[[headers]] + for = "/schemas/1.*" + [headers.values] + content-type = "application/yaml" + +[[headers]] + for = "/schemas/2.*" + [headers.values] + content-type = "application/yaml" + [[headers]] - for = "/schemas/:version" + for = "/schemas/3.*" [headers.values] content-type = "application/yaml"