Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use doctoc to automatically generate TOCs #2213

Merged
merged 4 commits into from
Jul 11, 2024
Merged

Use doctoc to automatically generate TOCs #2213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0f13374
Use doctoc to automatically generate TOCs
lucacome Jul 9, 2024
f31734c
Merge branch 'main' into chore/toc
lucacome Jul 9, 2024
52fe2ed
Merge branch 'main' into chore/toc
lucacome Jul 10, 2024
c9eb47f
Merge branch 'main' into chore/toc
lucacome Jul 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,12 @@ repos:
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, prettier, markdownlint-cli2, yamllint]
autofix_prs: false
31 changes: 17 additions & 14 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,23 @@
The following is a set of guidelines for contributing to NGINX Gateway Fabric. We really appreciate that you are
considering contributing!

## Table Of Contents

[Ask a Question](#ask-a-question)

[Getting Started](#getting-started)

[Contributing](#contributing)

- [Issues and Discussions](#issues-and-discussions)
- [Development Guide](#development-guide)

[Code of Conduct](CODE_OF_CONDUCT.md)

[Contributor License Agreement](#contributor-license-agreement)
<!-- 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)
- [Issues and Discussions](#issues-and-discussions)
- [Open a Discussion](#open-a-discussion)
- [Report a Bug](#report-a-bug)
- [Suggest an Enhancement](#suggest-an-enhancement)
- [Issue lifecycle](#issue-lifecycle)
- [Development Guide](#development-guide)
- [Contributor License Agreement](#contributor-license-agreement)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Ask a Question

Expand Down
34 changes: 29 additions & 5 deletions docs/developer/go-style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,37 @@ Once you have a good grasp of these general best practices, you can then explore
These guidelines will often build upon the foundation set by the general best practices and provide additional
recommendations tailored to the project's specific requirements and coding style.

<!-- 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

1. [General Guidelines](#general-guidelines)
2. [Error Handling](#error-handling)
3. [Logging](#logging)
4. [Concurrency](#concurrency)
5. [Recommended/Situational Guidelines](#recommended--situational)
- [General Guidelines](#general-guidelines)
- [Use the empty struct `struct{}` for sentinel values](#use-the-empty-struct-struct-for-sentinel-values)
- [Consistent Line Breaks](#consistent-line-breaks)
- [Do not copy sync entities](#do-not-copy-sync-entities)
- [Construct slices with known capacity](#construct-slices-with-known-capacity)
- [Accept interfaces and return structs](#accept-interfaces-and-return-structs)
- [Use contexts in a viral fashion](#use-contexts-in-a-viral-fashion)
- [Do not use templates to replace interface types](#do-not-use-templates-to-replace-interface-types)
- [Do not use booleans as function parameters](#do-not-use-booleans-as-function-parameters)
- [Use dependency injection to separate concerns](#use-dependency-injection-to-separate-concerns)
- [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)
- [Error Handling](#error-handling)
- [Prefer inline error handling](#prefer-inline-error-handling)
- [Do not filter context when returning errors](#do-not-filter-context-when-returning-errors)
- [Only handle errors once](#only-handle-errors-once)
- [Libraries should return errors for callers to handle](#libraries-should-return-errors-for-callers-to-handle)
- [Callers should handle errors and pass them up the stack for notification](#callers-should-handle-errors-and-pass-them-up-the-stack-for-notification)
- [Use panics for unrecoverable errors or programming errors](#use-panics-for-unrecoverable-errors-or-programming-errors)
- [Logging](#logging)
- [Concurrency](#concurrency)
- [Recommended / Situational](#recommended--situational)
- [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)
- [Reduce the number of stored pointers. Structures should store instances whenever possible](#reduce-the-number-of-stored-pointers-structures-should-store-instances-whenever-possible)
- [Pass pointers down the stack not up](#pass-pointers-down-the-stack-not-up)
- [Using interface types will cause unavoidable heap allocations](#using-interface-types-will-cause-unavoidable-heap-allocations)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## General Guidelines

Expand Down
60 changes: 29 additions & 31 deletions docs/developer/logging-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,39 +5,37 @@ This document describes the logging guidelines for the control plane of NGINX Ga
> The data plane logging is not covered here: such a concern is owned by NGINX developers, and NGF developers
> don't have control over it.

<!-- 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

<!-- TOC -->

- [Logging Guidelines](#logging-guidelines)
- [Table of Contents](#table-of-contents)
- [Requirements](#requirements)
- [User Stories](#user-stories)
- [Common Stories](#common-stories)
- [Stories For User](#stories-for-user)
- [Stories For Developers](#stories-for-developers)
- [Logging Library Choice](#logging-library-choice)
- [Guidelines](#guidelines)
- [How to Log](#how-to-log)
- [Log Levels](#log-levels)
- [Log Messages](#log-messages)
- [Context in Messages](#context-in-messages)
- [Examples of Log Messages](#examples-of-log-messages)
- [Message Guidelines](#message-guidelines)
- [Log Formatting](#log-formatting)
- [When to Log](#when-to-log)
- [What not to Log](#what-not-to-log)
- [Performance](#performance)
- [Logger Dependency in Code](#logger-dependency-in-code)
- [Logger Initialization](#logger-initialization)
- [Logger Injection](#logger-injection)
- [Special Case - Reconciler](#special-case---reconciler)
- [Unit Tests](#unit-tests)
- [External Libraries](#external-libraries)
- [Evolution](#evolution)
- [External Resources](#external-resources)

<!-- TOC -->
- [Requirements](#requirements)
- [User Stories](#user-stories)
- [Common Stories](#common-stories)
- [Stories For User](#stories-for-user)
- [Stories For Developers](#stories-for-developers)
- [Logging Library Choice](#logging-library-choice)
- [Guidelines](#guidelines)
- [How to Log](#how-to-log)
- [Log Levels](#log-levels)
- [Log Messages](#log-messages)
- [Context in Messages](#context-in-messages)
- [Examples of Log Messages](#examples-of-log-messages)
- [Message Guidelines](#message-guidelines)
- [Log Formatting](#log-formatting)
- [When to Log](#when-to-log)
- [What not to Log](#what-not-to-log)
- [Performance](#performance)
- [Logger Dependency in Code](#logger-dependency-in-code)
- [Logger Initialization](#logger-initialization)
- [Logger Injection](#logger-injection)
- [Special Case - Reconciler](#special-case---reconciler)
- [Unit Tests](#unit-tests)
- [External Libraries](#external-libraries)
- [Evolution](#evolution)
- [External Resources](#external-resources)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Requirements

Expand Down
20 changes: 20 additions & 0 deletions docs/developer/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,26 @@ This guide will assist you in setting up your development environment for NGINX
to build, install, and execute tasks necessary for submitting pull requests. By following this guide, you'll have a
fully prepared development environment that allows you to contribute to the project effectively.

<!-- 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

- [Setup Your Development Environment](#setup-your-development-environment)
- [Build the Binary and Images](#build-the-binary-and-images)
- [Setting GOARCH](#setting-goarch)
- [Build the Binary](#build-the-binary)
- [Build the Images](#build-the-images)
- [Build the Images with NGINX Plus](#build-the-images-with-nginx-plus)
- [Deploy on Kind](#deploy-on-kind)
- [Run Examples](#run-examples)
- [Run the Unit Tests](#run-the-unit-tests)
- [Gateway API Conformance Testing](#gateway-api-conformance-testing)
- [Run the Linter](#run-the-linter)
- [Run the Helm Linter](#run-the-helm-linter)
- [Update all the generated files](#update-all-the-generated-files)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Setup Your Development Environment

Follow these steps to set up your development environment.
Expand Down
12 changes: 12 additions & 0 deletions docs/developer/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

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

<!-- 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

- [Versioning](#versioning)
- [Release Planning and Development](#release-planning-and-development)
- [Releasing](#releasing)
- [Major or Minor Release](#major-or-minor-release)
- [Patch Release](#patch-release)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Versioning

NGF uses semantic versioning for its releases. For more information, see https://semver.org.
Expand Down
106 changes: 53 additions & 53 deletions docs/proposals/nginx-extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,61 +8,61 @@

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.

<!-- 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

<!-- TOC -->
- [Extensions for NGINX Features](#extensions-for-nginx-features)
- [Summary](#summary)
- [Table of Contents](#table-of-contents)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Gateway API Extensions](#gateway-api-extensions)
- [GatewayClass Parameters Ref](#gatewayclass-parameters-ref)
- [Issues with `parametersRef`](#issues-with-parametersref)
- [Infrastructure API](#infrastructure-api)
- [TLS Options](#tls-options)
- [Filters](#filters)
- [BackendRef](#backendref)
- [Policy](#policy)
- [Direct Policy Attachment](#direct-policy-attachment)
- [Inherited Policy Attachment](#inherited-policy-attachment)
- [Hierarchy](#hierarchy)
- [Challenges of Policy Attachment](#challenges-of-policy-attachment)
- [Prioritized NGINX Features](#prioritized-nginx-features)
- [High-Priority Features](#high-priority-features)
- [Medium-Priority Features](#medium-priority-features)
- [Low-Priority Features](#low-priority-features)
- [Features with Active Gateway API Enhancement Proposals](#features-with-active-gateway-api-enhancement-proposals)
- [Grouping the Features](#grouping-the-features)
- [API](#api)
- [Gateway Settings](#gateway-settings)
- [Future Work](#future-work)
- [Alternatives](#alternatives)
- [Response Modification](#response-modification)
- [Future Work](#future-work-1)
- [Alternatives](#alternatives-1)
- [TLS Settings](#tls-settings)
- [Future Work](#future-work-2)
- [Alternatives](#alternatives-2)
- [Client Settings](#client-settings)
- [Future Work](#future-work-3)
- [Alternatives](#alternatives-3)
- [Upstream Settings](#upstream-settings)
- [Alternatives](#alternatives-4)
- [Authentication](#authentication)
- [Future Work](#future-work-4)
- [Alternatives](#alternatives-5)
- [Observability](#observability)
- [Future Work](#future-work-5)
- [Alternatives](#alternatives-6)
- [Proxy Settings](#proxy-settings)
- [Future Work](#future-work-6)
- [Alternatives](#alternatives-7)
- [Testing](#testing)
- [Security Considerations](#security-considerations)
- [Alternatives Considered](#alternatives-considered)
- [References](#references)
<!-- TOC -->
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Gateway API Extensions](#gateway-api-extensions)
- [GatewayClass Parameters Ref](#gatewayclass-parameters-ref)
- [Issues with `parametersRef`](#issues-with-parametersref)
- [Infrastructure API](#infrastructure-api)
- [TLS Options](#tls-options)
- [Filters](#filters)
- [BackendRef](#backendref)
- [Policy](#policy)
- [Direct Policy Attachment](#direct-policy-attachment)
- [Inherited Policy Attachment](#inherited-policy-attachment)
- [Hierarchy](#hierarchy)
- [Direct or Indirect?](#direct-or-indirect)
- [Challenges of Policy Attachment](#challenges-of-policy-attachment)
- [Prioritized NGINX Features](#prioritized-nginx-features)
- [High-Priority Features](#high-priority-features)
- [Medium-Priority Features](#medium-priority-features)
- [Low-Priority Features](#low-priority-features)
- [Features with Active Gateway API Enhancement Proposals](#features-with-active-gateway-api-enhancement-proposals)
- [Grouping the Features](#grouping-the-features)
- [API](#api)
- [Gateway Settings](#gateway-settings)
- [Future Work](#future-work)
- [Alternatives](#alternatives)
- [Response Modification](#response-modification)
- [Future Work](#future-work-1)
- [Alternatives](#alternatives-1)
- [TLS Settings](#tls-settings)
- [Future Work](#future-work-2)
- [Alternatives](#alternatives-2)
- [Client Settings](#client-settings)
- [Future Work](#future-work-3)
- [Alternatives](#alternatives-3)
- [Upstream Settings](#upstream-settings)
- [Alternatives](#alternatives-4)
- [Authentication](#authentication)
- [Future Work](#future-work-4)
- [Alternatives](#alternatives-5)
- [Observability](#observability)
- [Future Work](#future-work-5)
- [Alternatives](#alternatives-6)
- [Proxy Settings](#proxy-settings)
- [Future Work](#future-work-6)
- [Alternatives](#alternatives-7)
- [Testing](#testing)
- [Security Considerations](#security-considerations)
- [Alternatives Considered](#alternatives-considered)
- [References](#references)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Goals

Expand Down
Loading
Loading