Add the specification to the docs

.gitignore

@@ -17,3 +17,8 @@ assets/jsconfig.json
 
 # IntelliJ
 *.iml
+
+# Generated content
+/content/en/docs/reference/specification/**/*.md
+/content/en/docs/reference/specification/**/*.png
+!/content/en/docs/reference/specification/_index.md

.htmltest.yml

@@ -2,3 +2,10 @@ DirectoryPath: public
 IgnoreDirectoryMissingTrailingSlash: true
 IgnoreAltMissing: true
 IgnoreInternalEmptyHash: true
+IgnoreInternalURLs:
+  # TODO: fix the source of these inlined TOC links
+  - HAHAHUGOSHORTCODE-s0-HBHB
+  - HAHAHUGOSHORTCODE-s1-HBHB
+  - HAHAHUGOSHORTCODE-s2-HBHB
+  - HAHAHUGOSHORTCODE-s5-HBHB
+  - HAHAHUGOSHORTCODE-s7-HBHB

assets/scss/_styles_project.scss

@@ -134,3 +134,8 @@ a:hover {
     margin-bottom: initial;
   }
 }
+
+.td-page-meta--child { display: none !important; }
+.otel-docs-spec {
+  .td-page-meta--edit { display: none !important; }
+}

config.yaml

@@ -159,3 +159,7 @@ module:
       target: static
     - source: content-modules/opentelemetry-specification/schemas
       target: static/schemas
+    - source: static/img
+      target: static/img
+    - source: content-modules/opentelemetry-specification/internal/img
+      target: static/img

content/en/docs/reference/_index.md

@@ -0,0 +1,5 @@
+---
+title: Reference
+weight: 100
+description: Reference material
+---

content/en/docs/reference/specification/_index.md

@@ -0,0 +1,88 @@
+---
+title: Specification
+no_list: true
+cascade:
+  body_class: otel-docs-spec
+  github_repo: &repo https://github.com/open-telemetry/opentelemetry-specification
+  github_subdir: specification
+  path_base_for_github_subdir: content/en/docs/reference/specification/
+  github_project_repo: *repo
+# Keep global values for this page. TODO: eliminate these overrides by moving the page into the spec repo.
+github_repo: &repo https://github.com/open-telemetry/opentelemetry.io
+github_subdir: ''
+path_base_for_github_subdir: ''
+github_project_repo: *repo
+weight: 2
+---
+
+The OpenTelemetry specification describes the cross-language requirements and expectations for all OpenTelemetry implementations. Substantive changes to the specification must be proposed using the [OpenTelemetry Enhancement Proposal](https://github.com/open-telemetry/oteps) process. Small changes, such as clarifications, wording changes, spelling/grammar corrections, etc. can be made directly via pull requests.
+
+Questions that needs additional attention can be brought to the regular
+specifications meeting. EU and US timezone friendly meeting is held every
+Tuesday at 8 AM pacific time. Meeting notes are held in the [google
+doc](https://docs.google.com/document/d/1-bCYkN-DWJq4jw1ybaDZYYmx-WAe6HnwfWbkm8d57v8/edit?usp=sharing).
+APAC timezone friendly meeting is held Tuesdays, 4PM pacific time. See
+[OpenTelemetry calendar](https://github.com/open-telemetry/community#calendar).
+
+Escalations to technical committee may be made over the
+[e-mail](https://github.com/open-telemetry/community#tc-technical-committee).
+Technical committee holds regular meetings, notes are held
+[here](https://docs.google.com/document/d/17v2RMZlJZkgoPYHZhIFTVdDqQMIAH8kzo8Sl2kP3cbY/edit?usp=sharing).
+
+## Table of Contents
+
+- [Overview](overview)
+- [Glossary](glossary)
+- [Versioning and stability for OpenTelemetry clients](versioning-and-stability)
+- [Library Guidelines](library-guidelines)
+  - [Package/Library Layout](library-layout)
+  - [General error handling guidelines](error-handling)
+- API Specification
+  - [Context](context/context)
+    - [Propagators](context/api-propagators)
+  - [Baggage](baggage/api)
+  - [Tracing](trace/api)
+  - [Metrics](metrics/api)
+- SDK Specification
+  - [Tracing](trace/sdk)
+  - [Resource](resource/sdk)
+  - [Configuration](sdk-configuration)
+- Data Specification
+  - [Semantic Conventions](overview#semantic-conventions)
+  - [Protocol](protocol)
+    - [Metrics](metrics/datamodel)
+    - [Logs](logs/data-model)
+- About the Project
+  - [Timeline](#project-timeline)
+  - [Notation Conventions and Compliance](#notation-conventions-and-compliance)
+  - [Versioning the Specification](#versioning-the-specification)
+  - [Acronym](#acronym)
+
+## Project Timeline
+
+The current project status as well as information on notable past releases is found at
+[the OpenTelemetry project page](/status/).
+
+Information about current work and future development plans is found at the
+[specification development milestones](https://github.com/open-telemetry/opentelemetry-specification/milestones).
+
+## Notation Conventions and Compliance
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the [specification](overview) are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [[RFC2119](https://tools.ietf.org/html/rfc2119)] [[RFC8174](https://tools.ietf.org/html/rfc8174)] when, and only when, they appear in all capitals, as shown here.
+
+An implementation of the [specification](overview) is not compliant if it fails to satisfy one or more of the "MUST", "MUST NOT", "REQUIRED", "SHALL", or "SHALL NOT" requirements defined in the [specification](overview).
+Conversely, an implementation of the [specification](overview) is compliant if it satisfies all the "MUST", "MUST NOT", "REQUIRED", "SHALL", and "SHALL NOT" requirements defined in the [specification](overview).
+
+## Versioning the Specification
+
+Changes to the [specification](overview) are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [CHANGELOG.md][]. Layout changes are not versioned. Specific implementations of the specification should specify which version they implement.
+
+Changes to the change process itself are not currently versioned but may be independently versioned in the future.
+
+## Acronym
+
+The official acronym used by the OpenTelemetry project is "OTel".
+
+Please refrain from using "OT" in order to avoid confusion with the now deprecated "OpenTracing" project.
+
+[CHANGELOG.md]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md

i18n/en.toml

@@ -1,8 +1,8 @@
+[post_view_this]
+other = "View page source"
 [Submit]
 other = "Submit"
-
 [Reset]
 other = "Reset"
-
 [Search]
 other = "Search"

layouts/docs/baseof.html

@@ -0,0 +1,34 @@
+{{/* docsy-delta */ -}}
+
+<!doctype html>
+<html lang="{{ .Site.Language.Lang }}" class="no-js">
+  <head>
+    {{ partial "head.html" . }}
+  </head>
+  <body class="td-{{ .Kind }}{{ with .Params.body_class }} {{.}}{{ end }}">
+    <header>
+      {{ partial "navbar.html" . }}
+    </header>
+    <div class="container-fluid td-outer">
+      <div class="td-main">
+        <div class="row flex-xl-nowrap">
+          <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
+            {{ partial "sidebar.html" . }}
+          </aside>
+          <aside class="d-none d-xl-block col-xl-2 td-sidebar-toc d-print-none">
+            {{ partial "page-meta-links.html" . }}
+            {{ partial "toc.html" . }}
+            {{ partial "taxonomy_terms_clouds.html" . }}
+          </aside>
+          <main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
+            {{ partial "version-banner.html" . }}
+            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
+            {{ block "main" . }}{{ end }}
+          </main>
+        </div>
+      </div>
+      {{ partial "footer.html" . }}
+    </div>
+    {{ partial "scripts.html" . }}
+  </body>
+</html>

layouts/partials/page-meta-links.html

@@ -0,0 +1,54 @@
+{{/* docsy-delta */ -}}
+{{ if .Path }}
+{{ $pathFormatted := replace .Path "\\" "/" -}}
+{{ $gh_repo := ($.Param "github_repo") -}}
+{{ $gh_url := ($.Param "github_url") -}}
+{{ $gh_subdir := ($.Param "github_subdir") -}}
+{{ $gh_project_repo := ($.Param "github_project_repo") -}}
+{{ $gh_branch := (default "master" ($.Param "github_branch")) -}}
+<div class="td-page-meta ml-2 pb-1 pt-2 mb-0">
+{{ if $gh_url -}}
+  <a href="{{ $gh_url }}" target="_blank"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
+{{ else if $gh_repo -}}
+  {{ $gh_repo_path := printf "%s/content/%s" $gh_branch $pathFormatted -}}
+  {{ if and ($gh_subdir) (.Site.Language.Lang) -}}
+    {{ $gh_repo_path = printf "%s/%s/content/%s/%s" $gh_branch $gh_subdir ($.Site.Language.Lang) $pathFormatted -}}
+  {{ else if .Site.Language.Lang -}}
+    {{ $gh_repo_path = printf "%s/content/%s/%s" $gh_branch ($.Site.Language.Lang) $pathFormatted -}}
+  {{ else if $gh_subdir -}}
+    {{ $gh_repo_path = printf "%s/%s/content/%s" $gh_branch $gh_subdir $pathFormatted -}}
+  {{ end -}}
+
+  {{/* Adjust $gh_repo_path based on path_base_for_github_subdir */ -}}
+  {{ $ghs_base := $.Param "path_base_for_github_subdir" -}}
+  {{ $ghs_rename := "" -}}
+  {{ if reflect.IsMap $ghs_base -}}
+    {{ $ghs_rename = $ghs_base.to -}}
+    {{ $ghs_base = $ghs_base.from -}}
+  {{ end -}}
+  {{ with $ghs_base -}}
+    {{ $gh_repo_path = replaceRE . $ghs_rename $gh_repo_path -}}
+  {{ end -}}
+
+  {{ $viewURL := printf "%s/tree/%s" $gh_repo $gh_repo_path -}}
+  {{ $editURL := printf "%s/edit/%s" $gh_repo $gh_repo_path -}}
+  {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}}
+  {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}}
+  {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}}
+  {{ $newPageURL := printf "%s/new/%s?%s"  $gh_repo $gh_repo_path $newPageQS -}}
+
+  <a href="{{ $viewURL }}" class="td-page-meta--view" target="_blank" rel="noopener"><i class="fa fa-file-alt fa-fw"></i> {{ T "post_view_this" }}</a>
+  <a href="{{ $editURL }}" class="td-page-meta--edit" target="_blank" rel="noopener"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
+  <a href="{{ $newPageURL }}" class="td-page-meta--child" target="_blank" rel="noopener"><i class="fa fa-edit fa-fw"></i> {{ T "post_create_child_page" }}</a>
+  <a href="{{ $issuesURL }}" class="td-page-meta--issue" target="_blank" rel="noopener"><i class="fab fa-github fa-fw"></i> {{ T "post_create_issue" }}</a>
+  {{ with $gh_project_repo -}}
+    {{ $project_issueURL := printf "%s/issues/new" . -}}
+    <a href="{{ $project_issueURL }}" class="td-page-meta--project-issue" target="_blank" rel="noopener"><i class="fas fa-tasks fa-fw"></i> {{ T "post_create_project_issue" }}</a>
+  {{ end -}}
+
+{{ end -}}
+{{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}}
+  <a id="print" href="{{ .Permalink | safeURL }}"><i class="fa fa-print fa-fw"></i> {{ T "print_entire_section" }}</a>
+{{ end }}
+</div>
+{{ end -}}

package.json

@@ -13,13 +13,13 @@
     "get:milestones": "node -r esm ./scripts/fetchMilestones.js",
     "postbuild:preview": "npm run _check-links",
     "postbuild:production": "npm run _check-links",
-    "prebuild:preview": "npm run submodule:get && npm run get:milestones",
-    "prebuild:production": "npm run submodule:get && npm run get:milestones",
-    "prebuild": "npm run submodule:get",
+    "prebuild:preview": "npm run submodule:get && npm run get:milestones && ./scripts/cp-spec-pages.sh",
+    "prebuild:production": "npm run submodule:get && npm run get:milestones && ./scripts/cp-spec-pages.sh",
+    "prebuild": "npm run submodule:get && ./scripts/cp-spec-pages.sh",
     "precheck-links": "npm run build",
     "preinstall": "npm run submodule:get",
-    "preserve": "npm run submodule:get",
-    "preserve:hugo": "npm run submodule:get",
+    "preserve": "npm run submodule:get && ./scripts/cp-spec-pages.sh",
+    "preserve:hugo": "npm run submodule:get && ./scripts/cp-spec-pages.sh",
     "schemas:update": "npm run submodule:update content-modules/opentelemetry-specification",
     "serve": "npm run _serve",
     "serve:hugo": "npm run _serve:hugo",

scripts/adjust-spec-pages.pl

@@ -0,0 +1,78 @@
+#!/usr/bin/perl -w -i
+
+$^W = 1;
+
+use strict;
+use warnings;
+use diagnostics;
+
+my $file = '';
+my $title = '';
+my $linkTitle = '';
+my $gD = 0;
+my $semConvRef = 'https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/README.md';
+
+sub printTitle() {
+  print "---\n";
+  print "title: $title\n";
+  print "weight: 1\n" if $title eq "Overview";
+  ($linkTitle) = $title =~ /^OpenTelemetry (.*)/;
+  $linkTitle = 'FaaS' if $ARGV =~ /faas-metrics.md$/;
+  $linkTitle = 'HTTP' if $ARGV =~ /http-metrics.md$/;
+  print "linkTitle: $linkTitle\n" if $linkTitle;
+  if ($ARGV =~ /_index.md$/) {
+    print "path_base_for_github_subdir:\n";
+    print "  from: content/en/docs/specification/(.*?)/_index.md\n";
+    print "  to: \$1/README.md\n";
+  }
+  print "---\n";
+}
+
+sub skipDetailsOrToc() {
+  while(<>) { last if /<\/details>|<!-- tocstop/; }
+}
+
+# main
+
+while(<>) {
+  # printf STDOUT "$ARGV Got: $_" if $gD;
+
+  if ($file ne $ARGV) {
+    $title = '';
+    $file = $ARGV;
+  }
+  if(! $title) {
+    ($title) = /^#\s+(.*)/;
+    printTitle() if $title;
+    next;
+  }
+
+  if(/<details>|<!-- toc/) {
+    skipDetailsOrToc();
+    next;
+  }
+
+  s|../semantic_conventions/README.md|$semConvRef| if $ARGV =~ /overview/;
+
+  # Bug fix from original source
+  s/#(#(instrument|set-status))/$1/;
+
+  # Images
+  s|(\.\./)?internal(/img/[-\w]+\.png)|$2|g;
+  s|(\]\()(img/.*?\))|$1../$2|g;
+
+  # Fix links that are to the title of the .md page
+  s|(/context/api-propagators.md)#propagators-api|$1|g;
+  s|(/semantic_conventions/faas.md)#function-as-a-service|$1|g;
+  s/#log-data-model/./;
+
+  s|\bREADME.md\b|_index.md|g;
+
+  # Rewrite inline links
+  s|\]\(([^:\)]*?\.md(#.*?)?)\)|]({{< relref "$1" >}})|g;
+
+  # Rewrite link defs
+  s|^(\[[^\]]+\]:\s*)([^:\s]*)(\s*(\(.*\))?)$|$1\{{< relref "$2" >}}$3|g;
+
+  print;
+}

scripts/cp-spec-pages.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+BASE_DIR=$(dirname $0)
+SPEC=content-modules/opentelemetry-specification/specification
+DEST=content/en/docs/reference/specification
+
+rm -Rf $DEST/[^_]*
+
+cp -R $SPEC/* $DEST/
+
+find $DEST/ -name "README.md" -exec sh -c 'f="{}"; mv -- "$f" "${f%README.md}_index.md"' \;
+
+FILES=`find $DEST -name "*.md" | grep -ve 'specification/_index.md$'`
+$BASE_DIR/adjust-spec-pages.pl $FILES
+
+echo "Specification pages copied and processed."