[GitHub] [airflow] mik-laj commented on a change in pull request #9290: Detect automatically the lack of reference to the guide in the operator descriptions

[GitBox <gi...@apache.org>]

mik-laj commented on a change in pull request #9290:
URL: https://github.com/apache/airflow/pull/9290#discussion_r440181201



##########
File path: docs/build
##########
@@ -127,6 +128,71 @@ def display_errors_summary() -> None:
     print("=" * 50)
 
 
+def find_existing_guide_operator_names():
+    operator_names = set()
+
+    paths = glob("howto/operator/**/*.rst", recursive=True)
+    for path in paths:
+        with open(path) as f:
+            operator_names |= set(re.findall(".. _howto/operator:(.+?):", f.read()))
+
+    return operator_names
+
+
+def extract_ast_class_def_by_name(ast_tree, class_name):
+    class ClassVisitor(ast.NodeVisitor):
+        def __init__(self):
+            self.found_class_node = None
+
+        def visit_ClassDef(self, node):
+            if node.name == class_name:
+                self.found_class_node = node
+
+    visitor = ClassVisitor()
+    visitor.visit(ast_tree)
+
+    return visitor.found_class_node
+
+
+def check_guide_links_in_operator_descriptions():
+    def generate_build_error(path, line_no, operator_name):
+        return DocBuildError(
+                    file_path=path,
+                    line_no=line_no,
+                    message=(
+                        f"Link to the guide is missing in operator's description: {operator_name}.\n"
+                        f"Please add link to the guide to the description in the following form:\n"
+                        f".. seealso::\n"
+                        f"For more information on how to use this operator, take a look at the guide:\n"
+                        f":ref:`howto/operator:{operator_name}`\n"

Review comment:
       ```suggestion
                           f"\n"
                           f".. seealso::\n"
                           f"    For more information on how to use this operator, take a look at the guide:\n"
                           f"    :ref:`howto/operator:{operator_name}`\n"
   ```
   This will make it easier to copy a snippet.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org