Improve schema-docs.md overview and navigation

schema-docs.md

@@ -1,107 +1,14 @@
 <!-- This file is generated using "make generate-markdown". Do not edit directly. -->
 
-* [Overview](#overview)
-* [Types](#types)
-  * [Aggregation](#aggregation)
-  * [AlwaysOffSampler](#alwaysoffsampler)
-  * [AlwaysOnSampler](#alwaysonsampler)
-  * [AttributeLimits](#attributelimits)
-  * [AttributeNameValue](#attributenamevalue)
-  * [AttributeType](#attributetype)
-  * [B3MultiPropagator](#b3multipropagator)
-  * [B3Propagator](#b3propagator)
-  * [BaggagePropagator](#baggagepropagator)
-  * [Base2ExponentialBucketHistogramAggregation](#base2exponentialbuckethistogramaggregation)
-  * [BatchLogRecordProcessor](#batchlogrecordprocessor)
-  * [BatchSpanProcessor](#batchspanprocessor)
-  * [CardinalityLimits](#cardinalitylimits)
-  * [ConsoleExporter](#consoleexporter)
-  * [DefaultAggregation](#defaultaggregation)
-  * [DropAggregation](#dropaggregation)
-  * [ExemplarFilter](#exemplarfilter)
-  * [ExperimentalContainerResourceDetector](#experimentalcontainerresourcedetector)
-  * [ExperimentalGeneralInstrumentation](#experimentalgeneralinstrumentation)
-  * [ExperimentalHostResourceDetector](#experimentalhostresourcedetector)
-  * [ExperimentalHttpClientInstrumentation](#experimentalhttpclientinstrumentation)
-  * [ExperimentalHttpInstrumentation](#experimentalhttpinstrumentation)
-  * [ExperimentalHttpServerInstrumentation](#experimentalhttpserverinstrumentation)
-  * [ExperimentalInstrumentation](#experimentalinstrumentation)
-  * [ExperimentalLanguageSpecificInstrumentation](#experimentallanguagespecificinstrumentation)
-  * [ExperimentalLoggerConfig](#experimentalloggerconfig)
-  * [ExperimentalLoggerConfigurator](#experimentalloggerconfigurator)
-  * [ExperimentalLoggerMatcherAndConfig](#experimentalloggermatcherandconfig)
-  * [ExperimentalMeterConfig](#experimentalmeterconfig)
-  * [ExperimentalMeterConfigurator](#experimentalmeterconfigurator)
-  * [ExperimentalMeterMatcherAndConfig](#experimentalmetermatcherandconfig)
-  * [ExperimentalOtlpFileExporter](#experimentalotlpfileexporter)
-  * [ExperimentalOtlpFileMetricExporter](#experimentalotlpfilemetricexporter)
-  * [ExperimentalPeerInstrumentation](#experimentalpeerinstrumentation)
-  * [ExperimentalPeerServiceMapping](#experimentalpeerservicemapping)
-  * [ExperimentalProbabilitySampler](#experimentalprobabilitysampler)
-  * [ExperimentalProcessResourceDetector](#experimentalprocessresourcedetector)
-  * [ExperimentalPrometheusMetricExporter](#experimentalprometheusmetricexporter)
-  * [ExperimentalResourceDetection](#experimentalresourcedetection)
-  * [ExperimentalResourceDetector](#experimentalresourcedetector)
-  * [ExperimentalServiceResourceDetector](#experimentalserviceresourcedetector)
-  * [ExperimentalTracerConfig](#experimentaltracerconfig)
-  * [ExperimentalTracerConfigurator](#experimentaltracerconfigurator)
-  * [ExperimentalTracerMatcherAndConfig](#experimentaltracermatcherandconfig)
-  * [ExplicitBucketHistogramAggregation](#explicitbuckethistogramaggregation)
-  * [ExporterDefaultHistogramAggregation](#exporterdefaulthistogramaggregation)
-  * [ExporterTemporalityPreference](#exportertemporalitypreference)
-  * [GrpcTls](#grpctls)
-  * [HttpTls](#httptls)
-  * [IncludeExclude](#includeexclude)
-  * [InstrumentType](#instrumenttype)
-  * [JaegerPropagator](#jaegerpropagator)
-  * [JaegerRemoteSampler](#jaegerremotesampler)
-  * [LastValueAggregation](#lastvalueaggregation)
-  * [LoggerProvider](#loggerprovider)
-  * [LogRecordExporter](#logrecordexporter)
-  * [LogRecordLimits](#logrecordlimits)
-  * [LogRecordProcessor](#logrecordprocessor)
-  * [MeterProvider](#meterprovider)
-  * [MetricProducer](#metricproducer)
-  * [MetricReader](#metricreader)
-  * [NameStringValuePair](#namestringvaluepair)
-  * [OpenCensusMetricProducer](#opencensusmetricproducer)
-  * [OpentelemetryConfiguration](#opentelemetryconfiguration)
-  * [OpenTracingPropagator](#opentracingpropagator)
-  * [OtlpGrpcExporter](#otlpgrpcexporter)
-  * [OtlpGrpcMetricExporter](#otlpgrpcmetricexporter)
-  * [OtlpHttpEncoding](#otlphttpencoding)
-  * [OtlpHttpExporter](#otlphttpexporter)
-  * [OtlpHttpMetricExporter](#otlphttpmetricexporter)
-  * [ParentBasedSampler](#parentbasedsampler)
-  * [PeriodicMetricReader](#periodicmetricreader)
-  * [Propagator](#propagator)
-  * [PullMetricExporter](#pullmetricexporter)
-  * [PullMetricReader](#pullmetricreader)
-  * [PushMetricExporter](#pushmetricexporter)
-  * [Resource](#resource)
-  * [Sampler](#sampler)
-  * [SimpleLogRecordProcessor](#simplelogrecordprocessor)
-  * [SimpleSpanProcessor](#simplespanprocessor)
-  * [SpanExporter](#spanexporter)
-  * [SpanLimits](#spanlimits)
-  * [SpanProcessor](#spanprocessor)
-  * [SumAggregation](#sumaggregation)
-  * [TextMapPropagator](#textmappropagator)
-  * [TraceContextPropagator](#tracecontextpropagator)
-  * [TraceIdRatioBasedSampler](#traceidratiobasedsampler)
-  * [TracerProvider](#tracerprovider)
-  * [View](#view)
-  * [ViewSelector](#viewselector)
-  * [ViewStream](#viewstream)
-  * [ZipkinSpanExporter](#zipkinspanexporter)
-* [Language Support Status](#language-support-status)
-  * [java](#java)
-* [SDK Extension Plugins](#sdk-extension-plugins)
+# Overview <a id="overview"></a>
 
 
-# Overview <a id="overview"></a>
+This document is an auto-generated view of the declarative configuration JSON schema and meta schema meant for improved consumability by humans.
+
+* [Types](#types) contains descriptions of all types and properties, with convenient linking between type references. [OpenTelemetryConfiguration](#opentelemetryconfiguration) is the root type and is a good starting point.
+* [Language Support Status](#language-support-status) provides all the details about each language's support in a single place. (Alternatively, each type definition has a table showing support status across languages.)
+* [SDK Extension Plugins](#sdk-extension-plugins) lists all the SDK extension plugin points.
 
-TODO
 # Types <a id="types"></a>
 
 ## Aggregation <a id="aggregation"></a>

scripts/generate-markdown.js

@@ -14,12 +14,18 @@ const jsonSchemaTypesByType = {};
 jsonSchemaTypes.forEach(type => jsonSchemaTypesByType[type.type] = type);
 
 const output = [];
-const headers = [];
 
 metaSchema.types.sort((a, b) => a.type.localeCompare(b.type));
 
 addHeader('Overview', 'overview', 1);
-output.push('TODO\n');
+output.push(`
+This document is an auto-generated view of the declarative configuration JSON schema and meta schema meant for improved consumability by humans.
+
+* [Types](#types) contains descriptions of all types and properties, with convenient linking between type references. [OpenTelemetryConfiguration](#opentelemetryconfiguration) is the root type and is a good starting point.
+* [Language Support Status](#language-support-status) provides all the details about each language's support in a single place. (Alternatively, each type definition has a table showing support status across languages.)
+* [SDK Extension Plugins](#sdk-extension-plugins) lists all the SDK extension plugin points.
+
+`);
 
 // Write types
 addHeader('Types', 'types', 1);
@@ -178,8 +184,6 @@ metaSchema.types.filter(metaSchemaType => metaSchemaType.isSdkExtensionPlugin)
         output.push(`* [${metaSchemaType.type}](#${metaSchemaType.type})\n`)
     });
 
-headers.push('\n\n');
-output.unshift(...headers);
 output.unshift('<!-- This file is generated using "make generate-markdown". Do not edit directly. -->\n\n')
 fs.writeFileSync(markdownDocPath, output.join(""));
 
@@ -206,7 +210,6 @@ function formatJsonSchemaPropertyType(jsonSchemaProperty, jsonSchemaTypesByType)
 }
 
 function addHeader(title, id, level) {
-    headers.push(`${'  '.repeat(level - 1)}* [${title}](#${id})\n`);
     output.push(`${'#'.repeat(level)} ${title} <a id="${id}"></a>\n\n`);
 }