Add TOC generator (#2208)

* Add TOC generator

.cspell.yaml

@@ -169,6 +169,7 @@ words:
     - signup
     - skyscanner
     - sloughter
+    - snyk
     - splk
     - stalnaker
     - subdir

.github/scripts/markdown-link-check-with-retry.sh

@@ -3,11 +3,11 @@
 # this script helps to reduce sporadic link check failures by retrying at a file-by-file level
 
 retry_count=3
+config="$(dirname "$0")/markdown-link-check-config.json"
 
 for file in "$@"; do
   for i in $(seq 1 $retry_count); do
-    if markdown-link-check --config "$(dirname "$0")/markdown-link-check-config.json" \
-                           "$file"; then
+    if npx --no -- markdown-link-check --quiet --progress --config "$config" "$file"; then
       break
     elif [[ $i -eq $retry_count ]]; then
       exit 1

.github/workflows/reusable-markdown-link-check.yml

@@ -9,14 +9,5 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install markdown-link-check
-        run: npm install -g [email protected]
-
       - name: Run markdown-link-check
-        run: |
-          find . -type f \
-                 -name '*.md' \
-                 -not -path './elections/2019/governance-committee-election.md' \
-                 -not -path './elections/2020/governance-committee-election.md' \
-                 -not -path './elections/*/governance-committee-candidates.md' \
-               | xargs .github/scripts/markdown-link-check-with-retry.sh
+        run: make markdown-link-check

Makefile

@@ -1,5 +1,7 @@
-.PHONY: table-generation
+# All documents to be used in spell check.
+ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' | sort)
 
+.PHONY: table-generation
 table-generation:
 	docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python ./scripts/update-sig-tables.py --install;
 
@@ -9,3 +11,27 @@ validate-sigs:
 
 table-check:
 	docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python ./scripts/update-sig-tables.py --install --check;
+
+.PHONY: markdown-link-check
+markdown-link-check:
+	@if ! npm ls markdown-link-check; then npm install; fi
+	find . -type f \
+		-name '*.md' \
+		-not -path './node_modules/*'
+		-not -path './elections/*/governance-committee-election.md' \
+		-not -path './elections/*/governance-committee-candidates.md' \
+		| xargs .github/scripts/markdown-link-check-with-retry.sh
+
+# This target runs markdown-toc on all files that contain
+# a pair of comments <!-- toc --> and <!-- tocstop -->.
+.PHONY: markdown-toc
+markdown-toc:
+	@if ! npm ls markdown-toc; then npm install; fi
+	@for f in $(ALL_DOCS); do \
+		if grep -q '<!-- tocstop -->' $$f; then \
+			echo markdown-toc: processing $$f; \
+				npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \
+		else \
+			echo markdown-toc: no TOC markers, skipping $$f; \
+		fi; \
+	done

areas-of-interest.md

@@ -14,12 +14,6 @@ the OpenTelemetry project are recommended to list their company
 affiliation, so that they may be contacted with vendor-specific
 concerns.
 
-<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
-
-<!-- toc -->
-
-<!-- tocstop -->
-
 ## Technical committee members
 
 ### [Armin Ruech](https://github.com/arminru), Dynatrace

assets.md

@@ -2,6 +2,41 @@
 
 This file is intended to list all the assets controlled by OpenTelemetry.
 
+<!-- Re-generate TOC with `make markdown-toc` -->
+
+<!-- toc -->
+
+- [Credential Storage](#credential-storage)
+- [Community Resource Accounts](#community-resource-accounts)
+  * [Actuated](#actuated)
+  * [AWS account](#aws-account)
+  * [Equinix bare metal](#equinix-bare-metal)
+  * [Grafana organization for SIG Security](#grafana-organization-for-sig-security)
+- [Artifact repositories](#artifact-repositories)
+  * [NuGet OpenTelemetry organization](#nuget-opentelemetry-organization)
+  * [MyGet OpenTelemetryCNCF account](#myget-opentelemetrycncf-account)
+  * [NPM OpenTelemetry Organization](#npm-opentelemetry-organization)
+  * [Maven](#maven)
+  * [PyPI](#pypi)
+- [Communication channels](#communication-channels)
+  * [opentelemetry-calendar-contributors Google Group](#opentelemetry-calendar-contributors-google-group)
+  * [OpenTelemetry Calendar Invites Google Group](#opentelemetry-calendar-invites-google-group)
+  * [Mailing list [email protected]](#mailing-list-cncf-opentelemetry-net-maintainerslistscncfio)
+  * [Mailing list [email protected]](#mailing-list-cncf-opentelemetry-rubylistscncfio)
+  * [Mailing list [email protected]](#mailing-list-cncf-opentelemetry-governancelistscncfio)
+  * [YouTube channel OpenTelemetry](#youtube-channel-opentelemetry)
+  * [Zoom accounts](#zoom-accounts)
+  * [Zapier account](#zapier-account)
+  * [Google Workspace accounts](#google-workspace-accounts)
+  * [Google account for [email protected]](#google-account-for-cncf-opentelemetry-governancelistscncfio)
+- [Bot accounts](#bot-accounts)
+  * [Easy CLA](#easy-cla)
+  * [Docker Hub](#docker-hub)
+  * [OpenTelemetry Bot](#opentelemetry-bot)
+- [Security](#security)
+
+<!-- tocstop -->
+
 ## Credential Storage
 
 - [1Password Teams](https://1password.com/)
@@ -175,6 +210,8 @@ Link: https://zapier.com
 
 ## Bot accounts
 
+Related: [Guidelines for adding new GitHub extensions](./docs/using-github-extensions.md).
+
 ### Easy CLA
 
 This is not really an OpenTelemetry asset as we do not have any credentials or admin access for it.