protodoc: Fix rst checker and load lazily (envoyproxy#29874)

Signed-off-by: Ryan Northey <[email protected]>

.azure-pipelines/stage/prechecks.yml

@@ -54,6 +54,7 @@ jobs:
   steps:
   - template: ../ci.yml
     parameters:
+      bazelBuildExtraOptions: --config=docs-ci
       ciTarget: $(CI_TARGET)
       cacheName: $(CI_TARGET)
       cacheTestResults: ${{ parameters.cacheTestResults }}

.bazelrc

@@ -48,6 +48,8 @@ build --action_env=BAZEL_FAKE_SCM_REVISION --host_action_env=BAZEL_FAKE_SCM_REVI
 
 build --test_summary=terse
 
+build:docs-ci --action_env=DOCS_RST_CHECK=1 --host_action_env=DOCS_RST_CHECK=1
+
 # TODO(keith): Remove once these 2 are the default
 build --incompatible_config_setting_private_default_visibility
 build --incompatible_enforce_config_setting_visibility

tools/protodoc/protodoc.py

@@ -3,7 +3,9 @@
 # for the underlying protos mentioned in this file. See
 # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html for Sphinx RST syntax.
 
+import importlib
 import logging
+import os
 import sys
 from collections import defaultdict
 from functools import cached_property, lru_cache
@@ -17,8 +19,6 @@
 from validate import validate_pb2
 from xds.annotations.v3 import status_pb2 as xds_status_pb2
 
-from envoy.code.check.checker import BackticksCheck
-
 from tools.api_proto_plugin import annotations, constants, plugin, visitor
 from tools.protodoc import jinja
 from tools.protodoc.data import data
@@ -140,8 +140,8 @@ class RstFormatVisitor(visitor.Visitor):
     """
 
     @cached_property
-    def backticks_check(self) -> BackticksCheck:
-        return BackticksCheck()
+    def backticks_check(self):
+        return importlib.import_module("envoy.code.check.checker").BackticksCheck()
 
     @property
     def contrib_extension_category_data(self):
@@ -253,7 +253,7 @@ def visit_message(self, msg_proto, ctx, nested_msgs: Iterable, nested_enums: Ite
         if msg_proto.options.map_entry or self._hide(ctx.leading_comment.annotations):
             return ''
         name = normalize_type_context_name(ctx.name)
-        return self.tpl_content.render(
+        message = self.tpl_content.render(
             header=self.tpl_header.render(
                 anchor=message_cross_ref_label(name),
                 title=name,
@@ -269,6 +269,13 @@ def visit_message(self, msg_proto, ctx, nested_msgs: Iterable, nested_enums: Ite
                 nested_msgs=nested_msgs,
                 nested_enums=nested_enums))
 
+        if not os.environ.get("DOCS_RST_CHECK"):
+            return message
+        error = self.backticks_check(message)
+        if error:
+            logger.warning(f"Bad RST ({msg_proto.name}): {error}")
+        return message
+
     @lru_cache
     def _comment(self, comment, show_wip_warning=False):
         """Format a comment string with additional RST for annotations.