[editorial] Ensure all ToCs are generated using markdown-toc

Makefile

@@ -40,7 +40,6 @@ $(MARKDOWN_TOC):
 # The recommended way to prepate a .md file for markdown-toc is
 # to add these comments:
 #
-#   <!-- Re-generate TOC with `make markdown-toc` -->
 #   <!-- toc -->
 #   <!-- tocstop -->
 .PHONY: markdown-toc

specification/baggage/api.md

@@ -3,21 +3,23 @@
 **Status**: [Stable, Feature-freeze](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
 
 - [Overview](#overview)
 - [Operations](#operations)
-  - [Get Value](#get-value)
-  - [Get All Values](#get-all-values)
-  - [Set Value](#set-value)
-  - [Remove Value](#remove-value)
+  * [Get Value](#get-value)
+  * [Get All Values](#get-all-values)
+  * [Set Value](#set-value)
+  * [Remove Value](#remove-value)
 - [Context Interaction](#context-interaction)
-  - [Clear Baggage in the Context](#clear-baggage-in-the-context)
+  * [Clear Baggage in the Context](#clear-baggage-in-the-context)
 - [Propagation](#propagation)
 - [Conflict Resolution](#conflict-resolution)
 
+<!-- tocstop -->
+
 </details>
 
 ## Overview

specification/common/attribute-naming.md

@@ -3,13 +3,16 @@
 **Status**: [Experimental](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
 
-- [Name Pluralization Guidelines](#name-pluralization-guidelines)
+<!-- toc -->
+
+- [Name Pluralization guidelines](#name-pluralization-guidelines)
 - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors)
 - [Recommendations for Application Developers](#recommendations-for-application-developers)
+- [otel.* Namespace](#otel-namespace)
+
+<!-- tocstop -->
 
 </details>
 

specification/common/common.md

@@ -3,13 +3,15 @@
 **Status**: [Stable, Feature-freeze](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
 
 - [Attribute](#attribute)
-  - [Attribute Limits](#attribute-limits)
-    - [Exempt Entities](#exempt-entities)
+  * [Attribute Limits](#attribute-limits)
+    + [Exempt Entities](#exempt-entities)
+
+<!-- tocstop -->
 
 </details>
 

specification/context/api-propagators.md

@@ -3,9 +3,9 @@
 **Status**: [Stable, Feature-Freeze](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
 
 - [Overview](#overview)
 - [Propagator Types](#propagator-types)
@@ -34,6 +34,10 @@ Table of Contents
   * [B3 Requirements](#b3-requirements)
     + [B3 Extract](#b3-extract)
     + [B3 Inject](#b3-inject)
+    + [Fields](#fields-1)
+    + [Configuration](#configuration)
+
+<!-- tocstop -->
 
 </details>
 

specification/context/context.md

@@ -3,18 +3,20 @@
 **Status**: [Stable, Feature-freeze](../document-status.md).
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
 
 - [Overview](#overview)
 - [Create a key](#create-a-key)
 - [Get value](#get-value)
 - [Set value](#set-value)
-- [Optional global operations](#optional-global-operations)
-  - [Get current Context](#get-current-context)
-  - [Attach Context](#attach-context)
-  - [Detach Context](#detach-context)
+- [Optional Global operations](#optional-global-operations)
+  * [Get current Context](#get-current-context)
+  * [Attach Context](#attach-context)
+  * [Detach Context](#detach-context)
+
+<!-- tocstop -->
 
 </details>
 

specification/glossary.md

@@ -4,7 +4,8 @@ This document defines some terms that are used across this specification.
 
 Some other fundamental terms are documented in the [overview document](overview.md).
 
-<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+<details>
+<summary>Table of Contents</summary>
 
 <!-- toc -->
 
@@ -38,6 +39,8 @@ Some other fundamental terms are documented in the [overview document](overview.
 
 <!-- tocstop -->
 
+</details>
+
 ## User Roles
 
 ### Application Owner

specification/metrics/README.md

@@ -3,20 +3,20 @@
 **Status**: [Experimental](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
 
-* [Overview](#overview)
+<!-- toc -->
+
+- [Overview](#overview)
   * [Design Goals](#design-goals)
   * [Concepts](#concepts)
-    * [API](#api)
-    * [SDK](#sdk)
-* [Specifications](#specifications)
-  * [Metrics API](./api.md)
-  * [Metrics SDK](./sdk.md)
-  * [Metrics Data Model and Protocol](./datamodel.md)
-  * [Semantic Conventions](./semantic_conventions/README.md)
+    + [API](#api)
+    + [SDK](#sdk)
+    + [Programming Model](#programming-model)
+- [Specifications](#specifications)
+- [References](#references)
+
+<!-- tocstop -->
 
 </details>
 

specification/metrics/api.md

@@ -3,37 +3,43 @@
 **Status**: [Stable](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
+<summary>Table of Contents</summary>
 
-* [Overview](#overview)
-* [MeterProvider](#meterprovider)
+<!-- toc -->
+
+- [Overview](#overview)
+- [MeterProvider](#meterprovider)
   * [MeterProvider operations](#meterprovider-operations)
-* [Meter](#meter)
+    + [Get a Meter](#get-a-meter)
+- [Meter](#meter)
   * [Meter operations](#meter-operations)
-* [Instrument](#instrument)
+- [Instrument](#instrument)
   * [Counter](#counter)
-    * [Counter creation](#counter-creation)
-    * [Counter operations](#counter-operations)
+    + [Counter creation](#counter-creation)
+    + [Counter operations](#counter-operations)
+      - [Add](#add)
   * [Asynchronous Counter](#asynchronous-counter)
-    * [Asynchronous Counter creation](#asynchronous-counter-creation)
-    * [Asynchronous Counter operations](#asynchronous-counter-operations)
-  * [Asynchronous Gauge](#asynchronous-gauge)
-    * [Asynchronous Gauge creation](#asynchronous-gauge-creation)
-    * [Asynchronous Gauge operations](#asynchronous-gauge-operations)
+    + [Asynchronous Counter creation](#asynchronous-counter-creation)
+    + [Asynchronous Counter operations](#asynchronous-counter-operations)
   * [Histogram](#histogram)
-    * [Histogram creation](#histogram-creation)
-    * [Histogram operations](#histogram-operations)
+    + [Histogram creation](#histogram-creation)
+    + [Histogram operations](#histogram-operations)
+      - [Record](#record)
+  * [Asynchronous Gauge](#asynchronous-gauge)
+    + [Asynchronous Gauge creation](#asynchronous-gauge-creation)
+    + [Asynchronous Gauge operations](#asynchronous-gauge-operations)
   * [UpDownCounter](#updowncounter)
-    * [UpDownCounter creation](#updowncounter-creation)
-    * [UpDownCounter operations](#updowncounter-operations)
+    + [UpDownCounter creation](#updowncounter-creation)
+    + [UpDownCounter operations](#updowncounter-operations)
+      - [Add](#add-1)
   * [Asynchronous UpDownCounter](#asynchronous-updowncounter)
-    * [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation)
-    * [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations)
-* [Measurement](#measurement)
-* [Compatibility requirements](#compatibility-requirements)
-* [Concurrency requirements](#concurrency-requirements)
+    + [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation)
+    + [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations)
+- [Measurement](#measurement)
+- [Compatibility requirements](#compatibility-requirements)
+- [Concurrency requirements](#concurrency-requirements)
+
+<!-- tocstop -->
 
 </details>
 

specification/metrics/datamodel.md

@@ -2,7 +2,8 @@
 
 **Status**: [Mixed](../document-status.md)
 
-<!-- Re-generate TOC with `make markdown-toc` -->
+<details>
+<summary>Table of Contents</summary>
 
 <!-- toc -->
 
@@ -48,6 +49,8 @@
 
 <!-- tocstop -->
 
+</details>
+
 ## Overview
 
 **Status**: [Stable](../document-status.md)

specification/metrics/sdk.md

@@ -3,25 +3,45 @@
 **Status**: [Feature-freeze](../document-status.md)
 
 <details>
-<summary>
-Table of Contents
-</summary>
-
-* [MeterProvider](#meterprovider)
-* [Attribute limits](#attribute-limits)
-* [Exemplar](#exemplar)
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [MeterProvider](#meterprovider)
+  * [Meter Creation](#meter-creation)
+  * [Shutdown](#shutdown)
+  * [ForceFlush](#forceflush)
+  * [View](#view)
+  * [Aggregation](#aggregation)
+    + [Drop Aggregation](#drop-aggregation)
+    + [Default Aggregation](#default-aggregation)
+    + [Sum Aggregation](#sum-aggregation)
+    + [Last Value Aggregation](#last-value-aggregation)
+    + [Histogram Aggregation](#histogram-aggregation)
+    + [Explicit Bucket Histogram Aggregation](#explicit-bucket-histogram-aggregation)
+- [Attribute limits](#attribute-limits)
+- [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
   * [ExemplarReservoir](#exemplarreservoir)
   * [Exemplar defaults](#exemplar-defaults)
-* [MetricReader](#metricreader)
+- [MetricReader](#metricreader)
+  * [MetricReader operations](#metricreader-operations)
+    + [Collect](#collect)
+  * [Shutdown](#shutdown-1)
   * [Periodic exporting MetricReader](#periodic-exporting-metricreader)
-* [MetricExporter](#metricexporter)
+- [MetricExporter](#metricexporter)
   * [Push Metric Exporter](#push-metric-exporter)
+    + [Interface Definition](#interface-definition)
+      - [Export(batch)](#exportbatch)
+      - [ForceFlush()](#forceflush)
+      - [Shutdown()](#shutdown)
   * [Pull Metric Exporter](#pull-metric-exporter)
-* [Defaults and configuration](#defaults-and-configuration)
-* [Numerical limits handling](#numerical-limits-handling)
-* [Compatibility requirements](#compatibility-requirements)
-* [Concurrency requirements](#concurrency-requirements)
+- [Defaults and configuration](#defaults-and-configuration)
+- [Numerical limits handling](#numerical-limits-handling)
+- [Compatibility requirements](#compatibility-requirements)
+- [Concurrency requirements](#concurrency-requirements)
+
+<!-- tocstop -->
 
 </details>
 
@@ -273,8 +293,8 @@ e.g. The View specifies an Aggregation by string name (i.e. "ExplicitBucketHisto
 # Use Histogram with custom boundaries
 meter_provider
   .add_view(
-    "X", 
-    aggregation="ExplicitBucketHistogram", 
+    "X",
+    aggregation="ExplicitBucketHistogram",
     aggregation_params={"Boundaries": [0, 10, 100]}
     )
 ```
@@ -424,7 +444,7 @@ A Metric SDK MUST allow `Exemplar` sampling to be disabled.  In this instance th
 
 A Metric SDK MUST sample `Exemplar`s only from measurements within the context of a sampled trace BY DEFAULT.
 
-A Metric SDK MUST allow exemplar sampling to leverage the configuration of a metric aggregator.  
+A Metric SDK MUST allow exemplar sampling to leverage the configuration of a metric aggregator.
 For example, Exemplar sampling of histograms should be able to leverage bucket boundaries.
 
 A Metric SDK SHOULD provide extensible hooks for Exemplar sampling, specifically:

specification/metrics/supplementary-guidelines.md

@@ -4,18 +4,24 @@ Note: this document is NOT a spec, it is provided to support the Metrics
 [API](./api.md) and [SDK](./sdk.md) specifications, it does NOT add any extra
 requirements to the existing specifications.
 
-Table of Contents:
+<details>
+<summary>Table of Contents</summary>
 
-* [Guidelines for instrumentation library
-  authors](#guidelines-for-instrumentation-library-authors)
+<!-- toc -->
+
+- [Guidelines for instrumentation library authors](#guidelines-for-instrumentation-library-authors)
   * [Instrument selection](#instrument-selection)
   * [Additive property](#additive-property)
   * [Monotonicity property](#monotonicity-property)
   * [Semantic convention](#semantic-convention)
-* [Guidelines for SDK authors](#guidelines-for-sdk-authors)
+- [Guidelines for SDK authors](#guidelines-for-sdk-authors)
   * [Aggregation temporality](#aggregation-temporality)
   * [Memory management](#memory-management)
 
+<!-- tocstop -->
+
+</details>
+
 ## Guidelines for instrumentation library authors
 
 ### Instrument selection

specification/overview.md

@@ -1,10 +1,7 @@
 # Overview
 
 <details>
-<summary>
-Table of Contents
-</summary>
-<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+<summary>Table of Contents</summary>
 
 <!-- toc -->