From c36f2c7798fc738f0cd15d7fca1e4c1ceb2308e9 Mon Sep 17 00:00:00 2001
From: phlax <phlax@users.noreply.github.com>
Date: Fri, 29 Sep 2023 17:41:52 +0100
Subject: [PATCH] protodoc: Fix rst checker and load lazily (#29874)

Signed-off-by: Ryan Northey <ryan@synca.io>
---
 .azure-pipelines/stage/prechecks.yml |  1 +
 .bazelrc                             |  2 ++
 tools/protodoc/protodoc.py           | 17 ++++++++++++-----
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/.azure-pipelines/stage/prechecks.yml b/.azure-pipelines/stage/prechecks.yml
index 5bd642c3c8c6..45d05891548c 100644
--- a/.azure-pipelines/stage/prechecks.yml
+++ b/.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 }}
diff --git a/.bazelrc b/.bazelrc
index 5a320d821c12..4cbb370a591c 100644
--- a/.bazelrc
+++ b/.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
diff --git a/tools/protodoc/protodoc.py b/tools/protodoc/protodoc.py
index 651d9b78e749..88ac1f7b66e7 100755
--- a/tools/protodoc/protodoc.py
+++ b/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.