[editorial] Move supplementary-guidelines into docs (#1284)

chalin · web-flow · commit de25ecbbffdc · 2024-07-29T10:06:52.000+02:00
Signed-off-by: Patrice Chalin &lt;pchalin@gmail.com&gt;
diff --git a/docs/README.md b/docs/README.md
@@ -42,3 +42,5 @@ Semantic Conventions by signals:
 * [Metrics](general/metrics.md): Semantic Conventions for metrics.
 * [Resource](resource/README.md): Semantic Conventions for resources.
 * [Trace](general/trace.md): Semantic Conventions for traces and spans.
+
+Also see, [Non-normative supplementary information](non-normative/README.md).
diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md
@@ -15,7 +15,7 @@ Some descriptions are also provided for populating general OpenTelemetry semanti
 
 ## Context Propagation
 
-See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation).
+See [compatibility](../non-normative/compatibility/aws.md#context-propagation).
 
 ## Common Attributes
 
diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md
@@ -168,7 +168,7 @@ For every message in the event, the [message system attributes][] (not message a
 the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be
 parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/context/api-propagators.md) and
 added as a link to the span. This means the span may have as many links as messages in the batch.
-See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info.
+See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info.
 
 - [`faas.trigger`][faas] MUST be set to `pubsub`.
 - [`messaging.operation.type`](/docs/messaging/messaging-spans.md) MUST be set to `process`.
@@ -181,7 +181,7 @@ corresponding to the SQS event. The [message system attributes][] (not message a
 the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be
 parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/context/api-propagators.md) and
 added as a link to the span.
-See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info.
+See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info.
 
 - [`faas.trigger`][faas] MUST be set to `pubsub`.
 - [`messaging.operation.type`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`.
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Attributes
-aliases: [docs/specs/semconv/general/general-attributes]
+aliases: [general-attributes]
 --->
 
 # General Attributes
diff --git a/docs/general/events.md b/docs/general/events.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Events
-aliases: [docs/specs/semconv/general/events-general]
+aliases: [events-general]
 --->
 
 # Semantic Conventions for Events
diff --git a/docs/general/logs.md b/docs/general/logs.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Logs
-aliases: [docs/specs/semconv/general/logs-general]
+aliases: [logs-general]
 --->
 
 # General Logs Attributes
diff --git a/docs/general/metrics.md b/docs/general/metrics.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Metrics
-aliases: [docs/specs/semconv/general/metrics-general]
+aliases: [metrics-general]
 --->
 
 # Metrics Semantic Conventions
diff --git a/docs/non-normative/README.md b/docs/non-normative/README.md
@@ -0,0 +1,11 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Non-normative
+path_base_for_github_subdir:
+  from: tmp/semconv/docs/non-normative/_index.md
+  to: non-normative/README.md
+--->
+
+# Non-normative supplementary information
+
+The pages in this section are **non-normative**, most are supplementary
+guidelines.
diff --git a/docs/non-normative/compatibility/README.md b/docs/non-normative/compatibility/README.md
@@ -0,0 +1,7 @@
+<!--- Hugo front matter used to generate the website version of this page:
+path_base_for_github_subdir:
+  from: tmp/semconv/docs/non-normative/compatibility/_index.md
+  to: non-normative/compatibility/README.md
+--->
+
+# Compatibility
diff --git a/docs/non-normative/compatibility/aws.md b/docs/non-normative/compatibility/aws.md
@@ -1,6 +1,10 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: AWS
+--->
+
 # Compatibility Considerations for AWS
 
-This document highlights compatibility considerations for OpenTelemetry
+This page highlights compatibility considerations for OpenTelemetry
 instrumentations when interacting with AWS managed services using an aws-sdk,
 a third-party library, or a direct HTTP request.
 
diff --git a/docs/non-normative/http-migration.md b/docs/non-normative/http-migration.md
@@ -1,4 +1,9 @@
-# HTTP semantic convention stability migration guide
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: HTTP migration
+aliases: [../http/migration-guide]
+--->
+
+# HTTP semantic convention stability migration
 
 Due to the significant number of modifications and the extensive user base
 affected by them, existing HTTP instrumentations published by
@@ -207,7 +212,7 @@ which case `{summary}` is `HTTP`.
 
 ### Migrating from `<= v1.16.0`
 
-This document does not cover these versions.
+This page does not cover these versions.
 
 [Host header]: https://tools.ietf.org/html/rfc7230#section-5.4
 [HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1
diff --git a/docs/non-normative/libraries.md b/docs/non-normative/libraries.md
@@ -1,3 +1,8 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Libraries
+# Renamed from: semantic_conventions_code_generation
+--->
+
 # Semantic convention libraries
 
 <!-- toc -->
@@ -115,4 +120,4 @@ Code-generation usually involves several steps which could be semi-automated:
 5. Fix lint violations in the auto-generated code (if any)
 6. Send the PR with new code to the corresponding repository
 
-Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh).
+Here are examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh).
diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh
@@ -27,7 +27,7 @@ fix_file() {
    "$1"
 }
 
-important_files=("docs" "model" "README.md" "supplementary-guidelines")
+important_files=("docs" "model" "README.md")
 
 # TODO - limit to markdown/yaml files?
 find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ fix_file() {`
`27`	`27`	`"$1"`
`28`	`28`	`}`
`29`	`29`
`30`		`-important_files=("docs" "model" "README.md" "supplementary-guidelines")`
	`30`	`+important_files=("docs" "model" "README.md")`
`31`	`31`
`32`	`32`	`# TODO - limit to markdown/yaml files?`
`33`	`33`	`find "${important_files[@]}" -type f -not -path '/.' -print0 \| while read -d $'\0' file; do`