Skip to content

Commit 6cbb524

Browse files
lucacomelucacome
authored
Use doctoc to automatically generate TOCs (#2213)
1 parent f13849a commit 6cbb524

8 files changed

+181
-113
lines changed

‎.pre-commit-config.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,12 @@ repos:
6363
hooks:
6464
- id: yamllint
6565

66+
- repo: https://github.com/thlorenz/doctoc
67+
rev: v2.2.0
68+
hooks:
69+
- id: doctoc
70+
args: [--update-only, --title, '## Table of Contents']
71+
6672
ci:
6773
skip: [golangci-lint-full, prettier, markdownlint-cli2, yamllint]
6874
autofix_prs: false

‎CONTRIBUTING.md

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,23 @@
33
The following is a set of guidelines for contributing to NGINX Gateway Fabric. We really appreciate that you are
44
considering contributing!
55

6-
## Table Of Contents
7-
8-
[Ask a Question](#ask-a-question)
9-
10-
[Getting Started](#getting-started)
11-
12-
[Contributing](#contributing)
13-
14-
- [Issues and Discussions](#issues-and-discussions)
15-
- [Development Guide](#development-guide)
16-
17-
[Code of Conduct](CODE_OF_CONDUCT.md)
18-
19-
[Contributor License Agreement](#contributor-license-agreement)
6+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
7+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
8+
## Table of Contents
9+
10+
- [Ask a Question](#ask-a-question)
11+
- [Getting Started](#getting-started)
12+
- [Project Structure](#project-structure)
13+
- [Contributing](#contributing)
14+
- [Issues and Discussions](#issues-and-discussions)
15+
- [Open a Discussion](#open-a-discussion)
16+
- [Report a Bug](#report-a-bug)
17+
- [Suggest an Enhancement](#suggest-an-enhancement)
18+
- [Issue lifecycle](#issue-lifecycle)
19+
- [Development Guide](#development-guide)
20+
- [Contributor License Agreement](#contributor-license-agreement)
21+
22+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2023

2124
## Ask a Question
2225

‎docs/developer/go-style-guide.md

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,37 @@ Once you have a good grasp of these general best practices, you can then explore
1010
These guidelines will often build upon the foundation set by the general best practices and provide additional
1111
recommendations tailored to the project's specific requirements and coding style.
1212

13+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
14+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
1315
## Table of Contents
1416

15-
1. [General Guidelines](#general-guidelines)
16-
2. [Error Handling](#error-handling)
17-
3. [Logging](#logging)
18-
4. [Concurrency](#concurrency)
19-
5. [Recommended/Situational Guidelines](#recommended--situational)
17+
- [General Guidelines](#general-guidelines)
18+
- [Use the empty struct `struct{}` for sentinel values](#use-the-empty-struct-struct-for-sentinel-values)
19+
- [Consistent Line Breaks](#consistent-line-breaks)
20+
- [Do not copy sync entities](#do-not-copy-sync-entities)
21+
- [Construct slices with known capacity](#construct-slices-with-known-capacity)
22+
- [Accept interfaces and return structs](#accept-interfaces-and-return-structs)
23+
- [Use contexts in a viral fashion](#use-contexts-in-a-viral-fashion)
24+
- [Do not use templates to replace interface types](#do-not-use-templates-to-replace-interface-types)
25+
- [Do not use booleans as function parameters](#do-not-use-booleans-as-function-parameters)
26+
- [Use dependency injection to separate concerns](#use-dependency-injection-to-separate-concerns)
27+
- [Required arguments should be provided via parameters and optional arguments provided functionally or with structs](#required-arguments-should-be-provided-via-parameters-and-optional-arguments-provided-functionally-or-with-structs)
28+
- [Error Handling](#error-handling)
29+
- [Prefer inline error handling](#prefer-inline-error-handling)
30+
- [Do not filter context when returning errors](#do-not-filter-context-when-returning-errors)
31+
- [Only handle errors once](#only-handle-errors-once)
32+
- [Libraries should return errors for callers to handle](#libraries-should-return-errors-for-callers-to-handle)
33+
- [Callers should handle errors and pass them up the stack for notification](#callers-should-handle-errors-and-pass-them-up-the-stack-for-notification)
34+
- [Use panics for unrecoverable errors or programming errors](#use-panics-for-unrecoverable-errors-or-programming-errors)
35+
- [Logging](#logging)
36+
- [Concurrency](#concurrency)
37+
- [Recommended / Situational](#recommended--situational)
38+
- [Use golang benchmark tests and pprof tools for profiling and identifying hot spots](#use-golang-benchmark-tests-and-pprof-tools-for-profiling-and-identifying-hot-spots)
39+
- [Reduce the number of stored pointers. Structures should store instances whenever possible](#reduce-the-number-of-stored-pointers-structures-should-store-instances-whenever-possible)
40+
- [Pass pointers down the stack not up](#pass-pointers-down-the-stack-not-up)
41+
- [Using interface types will cause unavoidable heap allocations](#using-interface-types-will-cause-unavoidable-heap-allocations)
42+
43+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2044

2145
## General Guidelines
2246

‎docs/developer/logging-guidelines.md

Lines changed: 29 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,37 @@ This document describes the logging guidelines for the control plane of NGINX Ga
55
> The data plane logging is not covered here: such a concern is owned by NGINX developers, and NGF developers
66
> don't have control over it.
77
8+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
9+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
810
## Table of Contents
911

10-
<!-- TOC -->
11-
12-
- [Logging Guidelines](#logging-guidelines)
13-
- [Table of Contents](#table-of-contents)
14-
- [Requirements](#requirements)
15-
- [User Stories](#user-stories)
16-
- [Common Stories](#common-stories)
17-
- [Stories For User](#stories-for-user)
18-
- [Stories For Developers](#stories-for-developers)
19-
- [Logging Library Choice](#logging-library-choice)
20-
- [Guidelines](#guidelines)
21-
- [How to Log](#how-to-log)
22-
- [Log Levels](#log-levels)
23-
- [Log Messages](#log-messages)
24-
- [Context in Messages](#context-in-messages)
25-
- [Examples of Log Messages](#examples-of-log-messages)
26-
- [Message Guidelines](#message-guidelines)
27-
- [Log Formatting](#log-formatting)
28-
- [When to Log](#when-to-log)
29-
- [What not to Log](#what-not-to-log)
30-
- [Performance](#performance)
31-
- [Logger Dependency in Code](#logger-dependency-in-code)
32-
- [Logger Initialization](#logger-initialization)
33-
- [Logger Injection](#logger-injection)
34-
- [Special Case - Reconciler](#special-case---reconciler)
35-
- [Unit Tests](#unit-tests)
36-
- [External Libraries](#external-libraries)
37-
- [Evolution](#evolution)
38-
- [External Resources](#external-resources)
39-
40-
<!-- TOC -->
12+
- [Requirements](#requirements)
13+
- [User Stories](#user-stories)
14+
- [Common Stories](#common-stories)
15+
- [Stories For User](#stories-for-user)
16+
- [Stories For Developers](#stories-for-developers)
17+
- [Logging Library Choice](#logging-library-choice)
18+
- [Guidelines](#guidelines)
19+
- [How to Log](#how-to-log)
20+
- [Log Levels](#log-levels)
21+
- [Log Messages](#log-messages)
22+
- [Context in Messages](#context-in-messages)
23+
- [Examples of Log Messages](#examples-of-log-messages)
24+
- [Message Guidelines](#message-guidelines)
25+
- [Log Formatting](#log-formatting)
26+
- [When to Log](#when-to-log)
27+
- [What not to Log](#what-not-to-log)
28+
- [Performance](#performance)
29+
- [Logger Dependency in Code](#logger-dependency-in-code)
30+
- [Logger Initialization](#logger-initialization)
31+
- [Logger Injection](#logger-injection)
32+
- [Special Case - Reconciler](#special-case---reconciler)
33+
- [Unit Tests](#unit-tests)
34+
- [External Libraries](#external-libraries)
35+
- [Evolution](#evolution)
36+
- [External Resources](#external-resources)
37+
38+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
4139

4240
## Requirements
4341

‎docs/developer/quickstart.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,26 @@ This guide will assist you in setting up your development environment for NGINX
44
to build, install, and execute tasks necessary for submitting pull requests. By following this guide, you'll have a
55
fully prepared development environment that allows you to contribute to the project effectively.
66

7+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
8+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
9+
## Table of Contents
10+
11+
- [Setup Your Development Environment](#setup-your-development-environment)
12+
- [Build the Binary and Images](#build-the-binary-and-images)
13+
- [Setting GOARCH](#setting-goarch)
14+
- [Build the Binary](#build-the-binary)
15+
- [Build the Images](#build-the-images)
16+
- [Build the Images with NGINX Plus](#build-the-images-with-nginx-plus)
17+
- [Deploy on Kind](#deploy-on-kind)
18+
- [Run Examples](#run-examples)
19+
- [Run the Unit Tests](#run-the-unit-tests)
20+
- [Gateway API Conformance Testing](#gateway-api-conformance-testing)
21+
- [Run the Linter](#run-the-linter)
22+
- [Run the Helm Linter](#run-the-helm-linter)
23+
- [Update all the generated files](#update-all-the-generated-files)
24+
25+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
26+
727
## Setup Your Development Environment
828

929
Follow these steps to set up your development environment.

‎docs/developer/release-process.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,18 @@
22

33
This document outlines the release process for NGINX Gateway Fabric (NGF).
44

5+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
7+
## Table of Contents
8+
9+
- [Versioning](#versioning)
10+
- [Release Planning and Development](#release-planning-and-development)
11+
- [Releasing](#releasing)
12+
- [Major or Minor Release](#major-or-minor-release)
13+
- [Patch Release](#patch-release)
14+
15+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
16+
517
## Versioning
618

719
NGF uses semantic versioning for its releases. For more information, see https://semver.org.

‎docs/proposals/nginx-extensions.md

Lines changed: 53 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -8,61 +8,61 @@
88

99
NGINX is highly configurable and offers rich features that can benefit our users. We want to expose this native NGINX configuration to our users through Gateway API extension points -- such as Policies and Filters. This Enhancement Proposal aims to identify the set of NGINX directives and parameters we will expose first, group them according to Gateway API role(s), NGINX contexts, and use cases, and propose the type of extension point for each group.
1010

11+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
12+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
1113
## Table of Contents
1214

13-
<!-- TOC -->
14-
- [Extensions for NGINX Features](#extensions-for-nginx-features)
15-
- [Summary](#summary)
16-
- [Table of Contents](#table-of-contents)
17-
- [Goals](#goals)
18-
- [Non-Goals](#non-goals)
19-
- [Gateway API Extensions](#gateway-api-extensions)
20-
- [GatewayClass Parameters Ref](#gatewayclass-parameters-ref)
21-
- [Issues with `parametersRef`](#issues-with-parametersref)
22-
- [Infrastructure API](#infrastructure-api)
23-
- [TLS Options](#tls-options)
24-
- [Filters](#filters)
25-
- [BackendRef](#backendref)
26-
- [Policy](#policy)
27-
- [Direct Policy Attachment](#direct-policy-attachment)
28-
- [Inherited Policy Attachment](#inherited-policy-attachment)
29-
- [Hierarchy](#hierarchy)
30-
- [Challenges of Policy Attachment](#challenges-of-policy-attachment)
31-
- [Prioritized NGINX Features](#prioritized-nginx-features)
32-
- [High-Priority Features](#high-priority-features)
33-
- [Medium-Priority Features](#medium-priority-features)
34-
- [Low-Priority Features](#low-priority-features)
35-
- [Features with Active Gateway API Enhancement Proposals](#features-with-active-gateway-api-enhancement-proposals)
36-
- [Grouping the Features](#grouping-the-features)
37-
- [API](#api)
38-
- [Gateway Settings](#gateway-settings)
39-
- [Future Work](#future-work)
40-
- [Alternatives](#alternatives)
41-
- [Response Modification](#response-modification)
42-
- [Future Work](#future-work-1)
43-
- [Alternatives](#alternatives-1)
44-
- [TLS Settings](#tls-settings)
45-
- [Future Work](#future-work-2)
46-
- [Alternatives](#alternatives-2)
47-
- [Client Settings](#client-settings)
48-
- [Future Work](#future-work-3)
49-
- [Alternatives](#alternatives-3)
50-
- [Upstream Settings](#upstream-settings)
51-
- [Alternatives](#alternatives-4)
52-
- [Authentication](#authentication)
53-
- [Future Work](#future-work-4)
54-
- [Alternatives](#alternatives-5)
55-
- [Observability](#observability)
56-
- [Future Work](#future-work-5)
57-
- [Alternatives](#alternatives-6)
58-
- [Proxy Settings](#proxy-settings)
59-
- [Future Work](#future-work-6)
60-
- [Alternatives](#alternatives-7)
61-
- [Testing](#testing)
62-
- [Security Considerations](#security-considerations)
63-
- [Alternatives Considered](#alternatives-considered)
64-
- [References](#references)
65-
<!-- TOC -->
15+
- [Goals](#goals)
16+
- [Non-Goals](#non-goals)
17+
- [Gateway API Extensions](#gateway-api-extensions)
18+
- [GatewayClass Parameters Ref](#gatewayclass-parameters-ref)
19+
- [Issues with `parametersRef`](#issues-with-parametersref)
20+
- [Infrastructure API](#infrastructure-api)
21+
- [TLS Options](#tls-options)
22+
- [Filters](#filters)
23+
- [BackendRef](#backendref)
24+
- [Policy](#policy)
25+
- [Direct Policy Attachment](#direct-policy-attachment)
26+
- [Inherited Policy Attachment](#inherited-policy-attachment)
27+
- [Hierarchy](#hierarchy)
28+
- [Direct or Indirect?](#direct-or-indirect)
29+
- [Challenges of Policy Attachment](#challenges-of-policy-attachment)
30+
- [Prioritized NGINX Features](#prioritized-nginx-features)
31+
- [High-Priority Features](#high-priority-features)
32+
- [Medium-Priority Features](#medium-priority-features)
33+
- [Low-Priority Features](#low-priority-features)
34+
- [Features with Active Gateway API Enhancement Proposals](#features-with-active-gateway-api-enhancement-proposals)
35+
- [Grouping the Features](#grouping-the-features)
36+
- [API](#api)
37+
- [Gateway Settings](#gateway-settings)
38+
- [Future Work](#future-work)
39+
- [Alternatives](#alternatives)
40+
- [Response Modification](#response-modification)
41+
- [Future Work](#future-work-1)
42+
- [Alternatives](#alternatives-1)
43+
- [TLS Settings](#tls-settings)
44+
- [Future Work](#future-work-2)
45+
- [Alternatives](#alternatives-2)
46+
- [Client Settings](#client-settings)
47+
- [Future Work](#future-work-3)
48+
- [Alternatives](#alternatives-3)
49+
- [Upstream Settings](#upstream-settings)
50+
- [Alternatives](#alternatives-4)
51+
- [Authentication](#authentication)
52+
- [Future Work](#future-work-4)
53+
- [Alternatives](#alternatives-5)
54+
- [Observability](#observability)
55+
- [Future Work](#future-work-5)
56+
- [Alternatives](#alternatives-6)
57+
- [Proxy Settings](#proxy-settings)
58+
- [Future Work](#future-work-6)
59+
- [Alternatives](#alternatives-7)
60+
- [Testing](#testing)
61+
- [Security Considerations](#security-considerations)
62+
- [Alternatives Considered](#alternatives-considered)
63+
- [References](#references)
64+
65+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
6666

6767
## Goals
6868

0 commit comments

Comments
 (0)