Add doctoc to automatically generate TOCs

lucacome · lucacome · commit 995dcd7aa132 · 2024-07-16T17:51:41.000-07:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -44,5 +44,12 @@ repos:
     rev: v1.35.1
     hooks:
       - id: yamllint
+
+  - repo: https://github.com/thlorenz/doctoc
+    rev: v2.2.0
+    hooks:
+      - id: doctoc
+        args: [--update-only, --title, "## Table of Contents"]
+
 ci:
   skip: [golangci-lint-full]
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,18 +5,24 @@ are considering contributing!
 
 ## Table Of Contents
 
-[Ask a Question](#ask-a-question)
-
-[Getting Started](#getting-started)
-
-[Contributing](#contributing)
-
-[Style Guides](#style-guides)
-
-- [Git Style Guide](#git-style-guide)
-- [Go Style Guide](#go-style-guide)
-
-[Code of Conduct](CODE_OF_CONDUCT.md)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Ask a Question](#ask-a-question)
+- [Getting Started](#getting-started)
+  - [Project Structure](#project-structure)
+- [Contributing](#contributing)
+  - [Report a Bug](#report-a-bug)
+  - [Suggest an Enhancement](#suggest-an-enhancement)
+  - [Open a Pull Request](#open-a-pull-request)
+  - [Issue lifecycle](#issue-lifecycle)
+  - [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement-cla)
+- [Style Guides](#style-guides)
+  - [Git Style Guide](#git-style-guide)
+  - [Go Style Guide](#go-style-guide)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Ask a Question
 
diff --git a/README.md b/README.md
@@ -18,6 +18,59 @@
 
 NGINX Prometheus exporter makes it possible to monitor NGINX or NGINX Plus using Prometheus.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Overview](#overview)
+- [Getting Started](#getting-started)
+  - [A Note about NGINX Ingress Controller](#a-note-about-nginx-ingress-controller)
+  - [Prerequisites](#prerequisites)
+  - [Running the Exporter in a Docker Container](#running-the-exporter-in-a-docker-container)
+  - [Running the Exporter Binary](#running-the-exporter-binary)
+- [Usage](#usage)
+  - [Command-line Arguments](#command-line-arguments)
+- [Exported Metrics](#exported-metrics)
+  - [Common metrics](#common-metrics)
+  - [Metrics for NGINX OSS](#metrics-for-nginx-oss)
+    - [Stub status metrics](#stub-status-metrics)
+  - [Metrics for NGINX Plus](#metrics-for-nginx-plus)
+    - [Connections](#connections)
+    - [HTTP](#http)
+    - [SSL](#ssl)
+    - [HTTP Server Zones](#http-server-zones)
+    - [Stream Server Zones](#stream-server-zones)
+    - [HTTP Upstreams](#http-upstreams)
+    - [Stream Upstreams](#stream-upstreams)
+    - [Stream Zone Sync](#stream-zone-sync)
+    - [Location Zones](#location-zones)
+    - [Resolver](#resolver)
+    - [HTTP Requests Rate Limiting](#http-requests-rate-limiting)
+    - [HTTP Connections Limiting](#http-connections-limiting)
+    - [Stream Connections Limiting](#stream-connections-limiting)
+    - [Cache](#cache)
+    - [Worker](#worker)
+- [Troubleshooting](#troubleshooting)
+- [Releases](#releases)
+  - [Docker images](#docker-images)
+  - [Binaries](#binaries)
+  - [Homebrew](#homebrew)
+  - [Snap](#snap)
+- [Building the Exporter](#building-the-exporter)
+  - [Building the Docker Image](#building-the-docker-image)
+  - [Building the Binary](#building-the-binary)
+- [Grafana Dashboard](#grafana-dashboard)
+- [SBOM (Software Bill of Materials)](#sbom-software-bill-of-materials)
+  - [Binaries](#binaries-1)
+  - [Docker Image](#docker-image)
+- [Provenance](#provenance)
+- [Contacts](#contacts)
+- [Contributing](#contributing)
+- [Support](#support)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Overview
 
 [NGINX](https://nginx.org) exposes a handful of metrics via the [stub_status
diff --git a/examples/basic_auth/README.md b/examples/basic_auth/README.md
@@ -7,6 +7,16 @@ password `password`.
 The full documentation for the web configuration can be found
 [here](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md).
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Running NGINX Prometheus Exporter with Web Configuration in Basic Authentication mode](#running-nginx-prometheus-exporter-with-web-configuration-in-basic-authentication-mode)
+- [Verification](#verification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Prerequisites
 
 - NGINX Prometheus Exporter binary. See the [main README](../../README.md) for installation instructions.
diff --git a/examples/kubernetes/README.md b/examples/kubernetes/README.md
@@ -2,6 +2,18 @@
 
 This example shows how to run NGINX Prometheus Exporter in a Kubernetes cluster.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Create a kind cluster](#create-a-kind-cluster)
+- [Deploy the NGINX Hello application and NGINX Prometheus Exporter](#deploy-the-nginx-hello-application-and-nginx-prometheus-exporter)
+- [Configure port forwarding](#configure-port-forwarding)
+- [Verification](#verification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Prerequisites
 
 - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) installed.
diff --git a/examples/systemd/README.md b/examples/systemd/README.md
@@ -2,6 +2,17 @@
 
 This example shows how to run NGINX Prometheus Exporter with systemd-activated socket.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Customization](#customization)
+- [Installation](#installation)
+- [Verification](#verification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Prerequisites
 
 - Linux machine with [systemd](https://www.freedesktop.org/wiki/Software/systemd/).
diff --git a/examples/tls/README.md b/examples/tls/README.md
@@ -7,6 +7,16 @@ Additionally, there are two example TLS files `server.crt` and `server.key` that
 The full documentation for the web configuration can be found
 [here](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md).
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Running NGINX Prometheus Exporter with Web Configuration in TLS mode](#running-nginx-prometheus-exporter-with-web-configuration-in-tls-mode)
+- [Verification](#verification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Prerequisites
 
 - NGINX Prometheus Exporter binary. See the [main README](../../README.md) for installation instructions.
diff --git a/grafana/README.md b/grafana/README.md
@@ -3,6 +3,16 @@
 We provide the official Grafana dashboard that visualizes the NGINX metrics exposed by the exporter. The dashboard
 allows you to filter metrics per instance or see the metrics from all instances.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installing the Dashboard](#installing-the-dashboard)
+- [Graphs](#graphs)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Prerequisites
 
 The dashboard has been tested with the following software versions:
