Ensure that a deprecated module has DOCUMENTATION.deprecated (#22090)

test/sanity/validate-modules/README.rst

@@ -117,6 +117,8 @@ Errors
 +---------+--------------------------------------------------------------------------------------------------------------------------------------------+
 | 317     | option is marked as required but specifies a default. Arguments with a default should not be marked as required                            |
 +---------+--------------------------------------------------------------------------------------------------------------------------------------------+
+| 318     | Module deprecated, but DOCUMENTATION.deprecated is missing                                                                                 |
++---------+--------------------------------------------------------------------------------------------------------------------------------------------+
 +---------+--------------------------------------------------------------------------------------------------------------------------------------------+
 | **4xx** | **Syntax**                                                                                                                                 |
 +---------+--------------------------------------------------------------------------------------------------------------------------------------------+

test/sanity/validate-modules/validate-modules

@@ -646,6 +646,13 @@ class ModuleValidator(Validator):
                          'with DOCUMENTATION.extends_documentation_fragment')
                     ))
 
+                if self.object_name.startswith('_') and not os.path.islink(self.object_path):
+                    if 'deprecated' not in doc or not doc.get('deprecated'):
+                        self.errors.append((
+                            318,
+                            'Module deprecated, but DOCUMENTATION.deprecated is missing'
+                        ))
+
                 self._validate_docs_schema(doc, doc_schema, 'DOCUMENTATION', 305)
                 self._check_version_added(doc)
                 self._check_for_new_args(doc)