envoyproxy/envoy

docs: verify config snippets are valid

Open

#8,837 opened on Oct 31, 2019

View on GitHub
 (2 comments) (0 reactions) (0 assignees)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

This is an aspirational work item, but it would be really nice if we could verify all of the config snippets in the docs are actually valid config. The way I would imagine this working is:

  1. Develop a new Sphinx plugin for an Envoy config snippet. This would identify the associated proto that it should load into.
  2. During doc generation, go through all snippets, and try to load the config YAML into the actual proto.

This would catch stale config. This might be a good GSoC project or a good item for someone that wants to do something really useful that is not C++.

Contributor guide

Research direction
Investigate the Envoy documentation build system, learn how Sphinx extensions work, and explore how to load protobuf definitions to validate YAML config snippets.
Tech stack
cpppython
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
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.
Clear
Prerequisites
GitPythonSphinxprotobuf
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65