feat: Allow disabling "missing type/annotation" warnings

Issue-mkdocstrings-437: mkdocstrings/mkdocstrings#437

Author: pawamoy

docs/reference/docstrings.md

@@ -128,6 +128,8 @@ The parser accepts a few options:
 - `returns_type_in_property_summary`: Whether to parse the return type of properties at the beginning of their summary: `str: Summary of the property`. Default: false.
 - `trim_doctest_flags`: Remove the [doctest flags] written as comments in `pycon` snippets within a docstring. These flags are used to alter the behavior of [doctest] when testing docstrings, and should not be visible in your docs. Default: true.
 - `warn_unknown_params`: Warn about parameters documented in docstrings that do not appear in the signature. Default: true.
+- `warn_missing_types`: Warn about missing type or annotation for parameters, return values, etc. Default: true.
+- `warnings`: Generally enable/disable warnings when parsing docstrings. Default: true. 
 
 ### Sections {#google-sections}
 
@@ -823,6 +825,8 @@ The parser accepts a few options:
 - `ignore_init_summary`: Ignore the first line in `__init__` methods' docstrings. Useful when merging `__init__` docstring into class' docstrings with mkdocstrings-python's [`merge_init_into_class`][merge_init] option. Default: false.
 - `trim_doctest_flags`: Remove the [doctest flags] written as comments in `pycon` snippets within a docstring. These flags are used to alter the behavior of [doctest] when testing docstrings, and should not be visible in your docs. Default: true.
 - `warn_unknown_params`: Warn about parameters documented in docstrings that do not appear in the signature. Default: true.
+- `warn_missing_types`: Warn about missing type or annotation for parameters, return values, etc. Default: true.
+- `warnings`: Generally enable/disable warnings when parsing docstrings. Default: true. 
 
 ### Sections {#numpydoc-sections}
 

src/griffe/_internal/docstrings/google.py

@@ -189,6 +189,7 @@ def _read_parameters(
     *,
     offset: int,
     warn_unknown_params: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> tuple[list[DocstringParameter], int]:
@@ -232,7 +233,7 @@ def _read_parameters(
         except (AttributeError, KeyError):
             default = None
 
-        if warnings and annotation is None:
+        if warnings and warn_missing_types and annotation is None:
             docstring_warning(docstring, line_number, f"No type or annotation for parameter '{name}'")
 
         if warnings and warn_unknown_params:
@@ -638,6 +639,7 @@ def _read_returns_section(
     offset: int,
     returns_multiple_items: bool = True,
     returns_named_value: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> tuple[DocstringSectionReturns | None, int]:
@@ -668,7 +670,7 @@ def _read_returns_section(
             # Try to retrieve the annotation from the docstring parent.
             annotation = _annotation_from_parent(docstring, gen_index=2, multiple=len(block) > 1, index=index)
 
-            if warnings and annotation is None:
+            if warnings and warn_missing_types and annotation is None:
                 returned_value = repr(name) if name else index + 1
                 docstring_warning(docstring, line_number, f"No type or annotation for returned value {returned_value}")
 
@@ -683,6 +685,7 @@ def _read_yields_section(
     offset: int,
     returns_multiple_items: bool = True,
     returns_named_value: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> tuple[DocstringSectionYields | None, int]:
@@ -713,7 +716,7 @@ def _read_yields_section(
             # Try to retrieve the annotation from the docstring parent.
             annotation = _annotation_from_parent(docstring, gen_index=0, multiple=len(block) > 1, index=index)
 
-            if warnings and annotation is None:
+            if warnings and warn_missing_types and annotation is None:
                 yielded_value = repr(name) if name else index + 1
                 docstring_warning(docstring, line_number, f"No type or annotation for yielded value {yielded_value}")
 
@@ -728,6 +731,7 @@ def _read_receives_section(
     offset: int,
     receives_multiple_items: bool = True,
     receives_named_value: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> tuple[DocstringSectionReceives | None, int]:
@@ -758,7 +762,7 @@ def _read_receives_section(
             # Try to retrieve the annotation from the docstring parent.
             annotation = _annotation_from_parent(docstring, gen_index=1, multiple=len(block) > 1, index=index)
 
-        if warnings and annotation is None:
+        if warnings and warn_missing_types and annotation is None:
             received_value = repr(name) if name else index + 1
             docstring_warning(docstring, line_number, f"No type or annotation for received value {received_value}")
 
@@ -861,6 +865,7 @@ def parse_google(
     receives_multiple_items: bool = True,
     receives_named_value: bool = True,
     warn_unknown_params: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> list[DocstringSection]:
@@ -888,6 +893,7 @@ def parse_google(
         returns_type_in_property_summary: Whether to parse the return type of properties
             at the beginning of their summary: `str: Summary of the property`.
         warn_unknown_params: Warn about documented parameters not appearing in the signature.
+        warn_missing_types: Warn about missing types/annotations for parameters, return values, etc.
         warnings: Whether to log warnings at all.
         **options: Additional parsing options.
 
@@ -909,6 +915,7 @@ def parse_google(
         "receives_multiple_items": receives_multiple_items,
         "receives_named_value": receives_named_value,
         "warn_unknown_params": warn_unknown_params,
+        "warn_missing_types": warn_missing_types,
         "warnings": warnings,
         **options,
     }

src/griffe/_internal/docstrings/numpy.py

@@ -225,6 +225,7 @@ def _read_parameters(
     *,
     offset: int,
     warn_unknown_params: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> tuple[list[DocstringParameter], int]:
@@ -263,7 +264,7 @@ def _read_parameters(
                     annotation = docstring.parent.parameters[name].annotation  # type: ignore[union-attr]
                     break
             else:
-                if warnings:
+                if warnings and warn_missing_types:
                     docstring_warning(docstring, new_offset, f"No types or annotations for parameters {names}")
         else:
             annotation = parse_docstring_annotation(annotation, docstring, log_level=LogLevel.debug)
@@ -897,6 +898,7 @@ def parse_numpy(
     ignore_init_summary: bool = False,
     trim_doctest_flags: bool = True,
     warn_unknown_params: bool = True,
+    warn_missing_types: bool = True,
     warnings: bool = True,
     **options: Any,
 ) -> list[DocstringSection]:
@@ -910,6 +912,7 @@ def parse_numpy(
         ignore_init_summary: Whether to ignore the summary in `__init__` methods' docstrings.
         trim_doctest_flags: Whether to remove doctest flags from Python example blocks.
         warn_unknown_params: Warn about documented parameters not appearing in the signature.
+        warn_missing_types: Warn about missing types/annotations for parameters, return values, etc.
         warnings: Whether to log warnings at all.
         **options: Additional parsing options.
 
@@ -927,6 +930,7 @@ def parse_numpy(
         "trim_doctest_flags": trim_doctest_flags,
         "ignore_init_summary": ignore_init_summary,
         "warn_unknown_params": warn_unknown_params,
+        "warn_missing_types": warn_missing_types,
         "warnings": warnings,
         **options,
     }