mik-laj commented on a change in pull request #9290:
URL: https://github.com/apache/airflow/pull/9290#discussion_r441098885
##########
File path: docs/build
##########
@@ -127,6 +129,76 @@ 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"\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"
+ )
+ )
+
+ # Extract operators for which there are existing .rst guides
+ operator_names = find_existing_guide_operator_names()
+
+ # Extract all potential python modules that can contain operators
+ python_module_paths = chain(
+ glob(f"{ROOT_PACKAGE_DIR}/operators/*.py"),
+ glob(f"{ROOT_PACKAGE_DIR}/sensors/*.py"),
+ glob(f"{ROOT_PACKAGE_DIR}/providers/**/operators/*.py",
recursive=True),
+ glob(f"{ROOT_PACKAGE_DIR}/providers/**/sensors/*.py", recursive=True),
+ )
+
+ for py_module_path in python_module_paths:
+ with open(py_module_path) as f:
+ py_content = f.read()
+ for existing_operator in operator_names:
+ if f"class {existing_operator}" not in py_content:
+ continue
+ # This is a potential file with necessary class definition.
+ # To make sure it's a real Python class definition, we build AST
tree
+ ast_tree = ast.parse(py_content)
+ class_def = extract_ast_class_def_by_name(ast_tree,
existing_operator)
+
+ # Real class definition is found and docstring does not contain
reference to the existing guide
+ if class_def is not None and
f":ref:`howto/operator:{existing_operator}`" not in
ast.get_docstring(class_def):
Review comment:
The documentation must build properly for this change to be accepted. In
some places we don't want links, so we have to handle it in the code.
----------------------------------------------------------------
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:
[email protected]
