WIP: Validating config in docs

docs/_ext/validating_code_block.py

@@ -0,0 +1,46 @@
+from typing import List
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+from sphinx.directives.code import CodeBlock
+from sphinx.errors import ExtensionError
+
+import subprocess
+
+class ValidatingCodeBlock(CodeBlock):
+
+    has_content = True
+    required_arguments = CodeBlock.required_arguments
+    optional_arguments = CodeBlock.optional_arguments
+    final_argument_whitespace = CodeBlock.final_argument_whitespace
+    option_spec = {
+        'type-name': directives.unchanged,
+    }
+    option_spec.update(CodeBlock.option_spec)
+
+    def run(self):
+        source, line = self.state_machine.get_source_and_line(self.lineno)
+        # built-in directives.unchanged_required option validator produces a confusing error message
+        if (self.options.get('type-name') == None):
+            raise ExtensionError("Expected type name in: {0} line: {1}".format(source, line))
+
+        process = subprocess.Popen(['bazel', 'run', '//tools/config_validation:validate_fragment', '--', self.options.get('type-name'), "-s", "\n".join(self.content)],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE)
+        stdout, stderr = process.communicate()
+        if (process.poll()):
+            raise ExtensionError("Failed config validation for type: '{0}' in: {1} line: {2}".format(self.options.get('type-name'), source, line))
+
+        self.options.pop('type-name', None)
+        return list(CodeBlock.run(self))
+
+def setup(app):
+    app.add_directive("validated-code-block", ValidatingCodeBlock)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/build.sh

@@ -126,6 +126,6 @@ cp -f "${CONFIGS_DIR}"/google-vrp/envoy-edge.yaml "${GENERATED_RST_DIR}"/configu
 
 rsync -rav  $API_DIR/diagrams "${GENERATED_RST_DIR}/api-docs"
 
-rsync -av "${SCRIPT_DIR}"/root/ "${SCRIPT_DIR}"/conf.py "${GENERATED_RST_DIR}"
+rsync -av "${SCRIPT_DIR}"/root/ "${SCRIPT_DIR}"/conf.py "${SCRIPT_DIR}"/_ext "${GENERATED_RST_DIR}"
 
 sphinx-build -W --keep-going -b html "${GENERATED_RST_DIR}" "${DOCS_OUTPUT_DIR}"

docs/conf.py

@@ -67,7 +67,10 @@ def setup(app):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinxcontrib.httpdomain', 'sphinx.ext.extlinks', 'sphinx.ext.ifconfig']
+
+sys.path.append(os.path.abspath("./_ext"))
+
+extensions = ['sphinxcontrib.httpdomain', 'sphinx.ext.extlinks', 'sphinx.ext.ifconfig', 'validating_code_block']
 extlinks = {
     'repo': ('https://github.com/envoyproxy/envoy/blob/{}/%s'.format(blob_sha), ''),
     'api': ('https://github.com/envoyproxy/envoy/blob/{}/api/%s'.format(blob_sha), ''),

docs/root/configuration/operations/runtime.rst

@@ -24,7 +24,8 @@ runtime <envoy_v3_api_msg_config.bootstrap.v3.LayeredRuntime>` bootstrap configu
 layering. Runtime settings in later layers override earlier layers. A typical configuration might
 be:
 
-.. code-block:: yaml
+.. validated-code-block:: yaml
+  :type-name: envoy.config.bootstrap.v3.LayeredRuntime
 
   layers:
   - name: static_layer_0

tools/config_validation/validate_fragment.py

@@ -51,6 +51,7 @@ def ValidateFragment(type_name, fragment):
 
 
 if __name__ == '__main__':
-  type_name, yaml_path = sys.argv[1:]
-  ValidateFragment(type_name, yaml.load(pathlib.Path(yaml_path).read_text(),
-                                        Loader=yaml.FullLoader))
+  type_name = sys.argv[1] 
+  yaml_path = sys.argv[2]
+  content = sys.argv[3] if (yaml_path == "-s") else pathlib.Path(yaml_path).read_text()
+  ValidateFragment(type_name, yaml.load(content, Loader=yaml.FullLoader))