envoyproxy/envoy

docs: automate listing all stock/built-in types for typed extensions

Open

#13,167 opened on Sep 18, 2020

View on GitHub
 (7 comments) (2 reactions) (1 assignee)C++ (5,373 forks)batch import
area/docshelp wantedpriority/high

Repository metrics

Stars
 (27,997 stars)
PR merge metrics
 (Avg merge 8d) (378 merged PRs in 30d)

Description

A major problem with our documentation is the user does not know what types are available for all of the typed extension points. Obviously we can't know all custom extensions and all bets are off if the user is doing a custom build, but we can ignore those cases because those users won't have any issues.

For everyone else, I think we should:

  1. Dump out all extensions in the stock build (either do this with bazel ahead of time, or somehow dump it out of the final exe). This is a map of extension type/category/link to docs, etc.
  2. Automate the documentation so all typed_extensions are printed with docs listing all stock types, as well as links to relevant docs, as well as sample config.

Contributor guide

Research direction
Investigate the existing typed extension points in Envoy's codebase, understand the Bazel build system to extract extension metadata, and create a script that dumps all stock types and generates documentation automatically.
Tech stack
cpp
Domain
documentationbackend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
C++Bazel
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60