From d9fbb6f32c3144c286a8e4999a6a0257b8e472e2 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Fri, 15 Oct 2021 11:04:22 -0400 Subject: [PATCH] Add Makefile target to auto-generate TOC via markdown-toc (#2020) --- .gitignore | 4 ++ Makefile | 37 +++++++++++++++---- .../semantic_conventions/faas-metrics.md | 2 + .../resource/semantic_conventions/README.md | 2 + .../trace/semantic_conventions/database.md | 21 +++++------ .../trace/semantic_conventions/exceptions.md | 2 +- .../trace/semantic_conventions/faas.md | 1 + .../trace/semantic_conventions/http.md | 19 +++++----- .../instrumentation/aws-lambda.md | 1 + .../trace/semantic_conventions/rpc.md | 23 ++++++------ .../semantic_conventions/span-general.md | 1 - 11 files changed, 71 insertions(+), 42 deletions(-) diff --git a/.gitignore b/.gitignore index 72d5f9267..71d4b9f93 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,7 @@ bin # Misspell binary internal/tools/bin + +# Node.js files for tools (e.g. markdown-toc) +node_modules/ +package-lock.json diff --git a/Makefile b/Makefile index 1762f8a0b..fe57073e1 100644 --- a/Makefile +++ b/Makefile @@ -5,8 +5,9 @@ PWD := $(shell pwd) TOOLS_DIR := ./internal/tools MISSPELL_BINARY=bin/misspell MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) -MARKDOWN_LINK_CHECK=markdown-link-check -MARKDOWN_LINT=markdownlint +MARKDOWN_LINK_CHECK=./node_modules/.bin/markdown-link-check +MARKDOWN_LINT=./node_modules/.bin/markdownlint +MARKDOWN_TOC=./node_modules/.bin/markdown-toc # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! @@ -27,17 +28,39 @@ misspell-correction: .PHONY: install-markdown-link-check install-markdown-link-check: - # TODO: Check for existence before installing - npm install -g $(MARKDOWN_LINK_CHECK) + npm install markdown-link-check .PHONY: markdown-link-check markdown-link-check: @for f in $(ALL_DOCS); do $(MARKDOWN_LINK_CHECK) --quiet --config .markdown_link_check_config.json $$f; done +.PHONY: install-markdown-toc +install-markdown-toc: + npm install markdown-toc + +.PHONY: markdown-toc +# This target runs markdown-toc on all files that contain +# a comment . +# +# The recommended way to prepate a .md file for markdown-toc is +# to add these comments: +# +# +# +# +markdown-toc: + @for f in $(ALL_DOCS); do \ + if grep -q '' $$f; then \ + echo markdown-toc: processing $$f; \ + $(MARKDOWN_TOC) --no-first-h1 -i $$f; \ + else \ + echo markdown-toc: no TOC markers, skipping $$f; \ + fi; \ + done + .PHONY: install-markdownlint install-markdownlint: - # TODO: Check for existence before installing - npm install -g markdownlint-cli + npm install markdownlint-cli .PHONY: markdownlint markdownlint: @@ -80,5 +103,5 @@ fix: table-generation misspell-correction # Attempt to install all the tools .PHONY: install-tools -install-tools: install-misspell install-markdownlint install-markdown-link-check +install-tools: install-misspell install-markdownlint install-markdown-link-check install-markdown-toc @echo "All tools installed" diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md index 6fe734e0c..3ff5b56d3 100644 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ b/specification/metrics/semantic_conventions/faas-metrics.md @@ -14,11 +14,13 @@ operations. By adding FaaS attributes to metric events it allows for finely tune + - [Metric Instruments](#metric-instruments) * [FaaS Invocations](#faas-invocations) - [Attributes](#attributes) - [References](#references) * [Metric References](#metric-references) + ## Metric Instruments diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 9cc0e23ed..cfcf14575 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -11,6 +11,8 @@ This document defines standard attributes for resources. These attributes are ty - [TODOs](#todos) - [Document Conventions](#document-conventions) +- [Attributes with Special Handling](#attributes-with-special-handling) + * [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) - [Telemetry SDK](#telemetry-sdk) diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 7fc983503..a9f55b8ad 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -6,17 +6,16 @@ -- [Semantic conventions for database client calls](#semantic-conventions-for-database-client-calls) - - [Connection-level attributes](#connection-level-attributes) - - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - - [Connection-level attributes for specific technologies](#connection-level-attributes-for-specific-technologies) - - [Call-level attributes](#call-level-attributes) - - [Call-level attributes for specific technologies](#call-level-attributes-for-specific-technologies) - - [Cassandra](#cassandra) - - [Examples](#examples) - - [MySQL](#mysql) - - [Redis](#redis) - - [MongoDB](#mongodb) +- [Connection-level attributes](#connection-level-attributes) + * [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) + * [Connection-level attributes for specific technologies](#connection-level-attributes-for-specific-technologies) +- [Call-level attributes](#call-level-attributes) + * [Call-level attributes for specific technologies](#call-level-attributes-for-specific-technologies) + + [Cassandra](#cassandra) +- [Examples](#examples) + * [MySQL](#mysql) + * [Redis](#redis) + * [MongoDB](#mongodb) diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md index b6ada64aa..aab024c44 100644 --- a/specification/trace/semantic_conventions/exceptions.md +++ b/specification/trace/semantic_conventions/exceptions.md @@ -9,7 +9,7 @@ exceptions. - [Recording an Exception](#recording-an-exception) - [Attributes](#attributes) - - [Stacktrace Representation](#stacktrace-representation) + * [Stacktrace Representation](#stacktrace-representation) diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index f5ba8f11b..4b0a22872 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -12,6 +12,7 @@ See also the [additional instructions for instrumenting AWS Lambda](instrumentat - [General Attributes](#general-attributes) + * [Function Name](#function-name) * [Difference between execution and instance](#difference-between-execution-and-instance) - [Incoming Invocations](#incoming-invocations) - [Outgoing Invocations](#outgoing-invocations) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 348ea1004..42120b5e0 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -10,16 +10,15 @@ and various HTTP versions like 1.1, 2 and SPDY. -- [Semantic conventions for HTTP spans](#semantic-conventions-for-http-spans) - - [Name](#name) - - [Status](#status) - - [Common Attributes](#common-attributes) - - [HTTP request and response headers](#http-request-and-response-headers) - - [HTTP client](#http-client) - - [HTTP server](#http-server) - - [HTTP server definitions](#http-server-definitions) - - [HTTP Server semantic conventions](#http-server-semantic-conventions) - - [HTTP client-server example](#http-client-server-example) +- [Name](#name) +- [Status](#status) +- [Common Attributes](#common-attributes) + * [HTTP request and response headers](#http-request-and-response-headers) +- [HTTP client](#http-client) +- [HTTP server](#http-server) + * [HTTP server definitions](#http-server-definitions) + * [HTTP Server semantic conventions](#http-server-semantic-conventions) +- [HTTP client-server example](#http-client-server-example) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index ae404da54..8486ec79d 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -24,6 +24,7 @@ use cases. * [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) * [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) +- [Resource Detector](#resource-detector) diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 49078143b..92edb4fab 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -9,18 +9,17 @@ This document defines how to describe remote procedure calls -- [Semantic conventions for RPC spans](#semantic-conventions-for-rpc-spans) - - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - - [Span name](#span-name) - - [Attributes](#attributes) - - [Service name](#service-name) - - [Events](#events) - - [Distinction from HTTP spans](#distinction-from-http-spans) - - [gRPC](#grpc) - - [gRPC Attributes](#grpc-attributes) - - [gRPC Status](#grpc-status) - - [JSON RPC](#json-rpc) - - [JSON RPC Attributes](#json-rpc-attributes) +- [Common remote procedure call conventions](#common-remote-procedure-call-conventions) + * [Span name](#span-name) + * [Attributes](#attributes) + + [Service name](#service-name) + * [Events](#events) + * [Distinction from HTTP spans](#distinction-from-http-spans) +- [gRPC](#grpc) + * [gRPC Attributes](#grpc-attributes) + * [gRPC Status](#grpc-status) +- [JSON RPC](#json-rpc) + * [JSON RPC Attributes](#json-rpc-attributes) diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index d27276c0e..1a600444e 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -11,7 +11,6 @@ Particular operations may refer to or require some of these attributes. - [General network connection attributes](#general-network-connection-attributes) - * [`net.transport` attribute](#nettransport-attribute) * [`net.*.name` attributes](#netname-attributes) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes)