Add the specification to the docs (#866)
* Add the specification to the docs * Add base mount point for static/img * Script cleanup, no change in behavior * Fix markdown link reference * Support repo links to spec repo * Remove GitHub tag, since it might not match the file version * Support repo links via page rename for index to README * Move spec to be below /reference * Replace Edit-page by View-page
This commit is contained in:
Patrice Chalin
GitHub
parent
0966ee2719
commit
c39f5295c2
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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; }
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
title: Reference
|
||||
weight: 100
|
||||
description: Reference material
|
||||
---
|
||||
|
|
@ -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
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
[post_view_this]
|
||||
other = "View page source"
|
||||
[Submit]
|
||||
other = "Submit"
|
||||
|
||||
[Reset]
|
||||
other = "Reset"
|
||||
|
||||
[Search]
|
||||
other = "Search"
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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 -}}
|
||||
10
package.json
10
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",
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
|
@ -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."
|
||||
Loading…
Reference in New Issue