search

envoyproxy / envoy

Cloud-native high-performance edge/middle/service proxy
https://www.envoyproxy.io
Apache License 2.0
24.85k stars 4.77k forks source link

docs: verify config snippets are valid #8837

Open mattklein123 opened 4 years ago

mattklein123 commented 4 years ago

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++.

phlax commented 4 years ago

i think this could be resolved as part of the work on the vscode plugin #13078

in terms of CI, a Sphinx plugin would be good - esp from pov of doc development if you are building the docs as you make changes, but...

there might be other ways we could do something more quickly - eg pushing the snippets into include files - which would probably make code snippets in the docs easier to lint more generally, not just config snippets

mattklein123 commented 4 years ago

@phlax sorry this should have been updated. Substantial work on this has already been done on this by @dmitri-d. See https://github.com/envoyproxy/envoy/pull/11394 and https://github.com/envoyproxy/envoy/tree/master/tools/config_validation.

This issue is now tracking trying to get more things to be validated and improving the tooling as needed.