Integrate Ruff docstring linting for Arm public APIs (#19934)

Add a RUFF_DOCS lintrunner target scoped to Arm public API files.

Signed-off-by: Sebastian Larsson <sebastian.larsson@arm.com>

Author: Sebastian-Larsson

.lintrunner.toml

@@ -683,6 +683,41 @@ command = [
     '@{{PATHSFILE}}',
 ]
 
+[[linter]]
+code = 'RUFF_DOCS'
+include_patterns = [
+  'backends/arm/__init__.py',
+  'backends/arm/common/arm_compile_spec.py',
+  'backends/arm/ethosu/**/*.py',
+  'backends/arm/quantizer/__init__.py',
+  'backends/arm/quantizer/arm_quantizer.py',
+  'backends/arm/tosa/partitioner.py',
+  'backends/arm/vgf/**/*.py',
+]
+exclude_patterns = [
+  'third-party/**',
+  '**/third-party/**',
+]
+command = [
+  'python',
+  '-m',
+  'lintrunner_adapters',
+  'run',
+  'ruff_linter',
+  '--config=pyproject.toml',
+  '--',
+  '@{{PATHSFILE}}',
+]
+init_command = [
+  'python',
+  '-m',
+  'lintrunner_adapters',
+  'run',
+  'pip_init',
+  '--dry-run={{DRYRUN}}',
+  '--requirement=requirements-lintrunner.txt',
+]
+
 [[linter]]
 code = 'DOCFORMATTER'
 include_patterns = ['backends/arm/**/*.py']

backends/arm/common/arm_compile_spec.py

@@ -28,7 +28,11 @@
 
 @dataclass(init=False)
 class ArmCompileSpec(ABC):
+    """Base compile specification for Arm backend targets."""
+
     class DebugMode(Enum):
+        """Debug artifact formats emitted during Arm lowering."""
+
         JSON = 1
         TOSA = 2
 
@@ -272,8 +276,10 @@ def _set_preserve_io_quantization(self, enabled: bool) -> "ArmCompileSpec":
         return self
 
     def _warn_if_redundant_preserve_io_quantization(self) -> None:
-        """Warn when preserve_io_quantization has no effect for INT-only
-        specs.
+        """Warn when preserve_io_quantization has no effect.
+
+        INT-only specs already preserve IO quantization naturally.
+
         """
         if (
             self.preserve_io_quantization
@@ -287,8 +293,7 @@ def _warn_if_redundant_preserve_io_quantization(self) -> None:
             )
 
     def _get_pass_pipeline_config(self) -> ArmPassPipelineConfig:
-        """Returns configuration that controls how the Arm pass pipeline should
-        behave.
+        """Return the configuration for the Arm pass pipeline.
 
         Subclasses may override to tweak defaults for specific targets.
 
@@ -298,8 +303,7 @@ def _get_pass_pipeline_config(self) -> ArmPassPipelineConfig:
         return self._pipeline_config
 
     def set_pass_pipeline_config(self, config: ArmPassPipelineConfig) -> None:
-        """Sets the configuration that controls how the Arm pass pipeline should
-        behave. Subclasses may override to tweak defaults for specific targets.
+        """Set the configuration for the Arm pass pipeline.
 
         Args:
             config: The custom ArmPassPipelineConfig to set.
@@ -317,18 +321,16 @@ def _create_default_pipeline_config(self) -> ArmPassPipelineConfig:
         return config
 
     def _get_intermediate_path(self) -> str | None:
-        """Gets the path used for dumping intermediate results such as tosa and
-        pte.
+        """Get the path used for dumping intermediate results.
 
         Returns:
-            Path where intermediate results are saved.
+            Path where TOSA and PTE intermediate results are saved.
 
         """
         return self.path_for_intermediates
 
     def dump_intermediate_artifacts_to(self, output_path: str | None):
-        """Sets a path for dumping intermediate results during such as tosa and
-        pte.
+        """Set a path for dumping TOSA and PTE intermediate results.
 
         Args:
             output_path: Path to dump intermediate results to.

backends/arm/ethosu/compile_spec.py

@@ -4,9 +4,7 @@
 # LICENSE file in the root directory of this source tree.
 
 from executorch.backends.arm.common.arm_compile_spec import ArmCompileSpec
-from executorch.backends.arm.common.pipeline_config import (  # noqa: unused
-    ArmPassPipelineConfig,
-)
+from executorch.backends.arm.common.pipeline_config import ArmPassPipelineConfig
 from executorch.backends.arm.tosa import (  # type: ignore[import-not-found]
     TosaSpecification,
 )

backends/arm/quantizer/arm_quantizer.py

@@ -117,7 +117,6 @@ def get_cond_while_submodules_ao(
     only the ``while_loop`` cond function is processed explicitly there.
 
     """
-
     if not apply_quantization:
         return get_cond_while_submodules(graph_module)
 
@@ -156,6 +155,7 @@ def get_symmetric_quantization_config(
         act_qmax (int): Maximum activation quantization value.
         weight_qmin (int): Minimum weight quantization value.
         weight_qmax (int): Maximum weight quantization value.
+        eps (float): Minimum scale value used by observers.
 
     Returns:
         QuantizationConfig: Quantization settings for activations, weights, and
@@ -525,14 +525,17 @@ def __init__(
 
     @property
     def tosa_spec(self):
+        """Return the TOSA specification used by the active quantizer."""
         return self.quantizer.tosa_spec
 
     @property
     def compile_spec(self):
+        """Return the compile specification used by the active quantizer."""
         return self.quantizer.compile_spec
 
     @property
     def global_config(self):
+        """Return the fallback quantization configuration."""
         return self.quantizer.global_config
 
     @global_config.setter
@@ -546,6 +549,7 @@ def global_config(self, value: Optional[QuantizationConfig]) -> None:
 
     @property
     def io_config(self):
+        """Return the input and output quantization configuration."""
         if isinstance(self.quantizer, _TOSAQuantizerV1):
             return self.quantizer.io_config
         else:
@@ -564,6 +568,7 @@ def io_config(self, value: Optional[QuantizationConfig]) -> None:
 
     @property
     def module_type_config(self):
+        """Return quantization configuration overrides by module type."""
         if isinstance(self.quantizer, _TOSAQuantizerV1):
             return self.quantizer.module_type_config
         else:
@@ -584,6 +589,7 @@ def module_type_config(
 
     @property
     def module_name_config(self):
+        """Return quantization configuration overrides by module name."""
         if isinstance(self.quantizer, _TOSAQuantizerV1):
             return getattr(self.quantizer, "module_name_config", {})
         else:
@@ -692,6 +698,7 @@ def set_node_finder(
             quantization_config (Optional[QuantizationConfig]): Configuration
                 describing quantization settings for nodes matched by the provided
                 NodeFinder. ``None`` indicates no quantization.
+            node_finder (NodeFinder): Predicate used to select nodes.
 
         """
         if self.use_composable_quantizer:
@@ -757,14 +764,18 @@ def annotate(self, model: GraphModule) -> GraphModule:
         return self.quantizer.annotate(model)
 
     def validate(self, model: GraphModule) -> None:
-        """Validate the quantization results. Currently, this includes:
-            - Ensure tensor inputs to each operator live on the same device.
+        """Validate the quantization results.
+
+        Currently, this ensures tensor inputs to each operator live on the same
+        device.
 
         Args:
             model (GraphModule): GraphModule being validated.
+
         Raises:
             ValueError: If tensor inputs for any operator span more than one
                 device.
+
         """
         for node in model.graph.nodes:
             if node.op != "call_function":
@@ -809,8 +820,7 @@ def _quantize_with_submodules(
         is_qat: bool = False,
         fold_quantize: bool = True,
     ):
-        """Quantizes a GraphModule in a way such that conditional submodules are
-        handled properly.
+        """Quantize a GraphModule with conditional submodule handling.
 
         Note: torchao's prepare_pt2e and convert_pt2e natively handle
         while_loop body_fn submodules, so we only manually process cond
@@ -823,8 +833,8 @@ def _quantize_with_submodules(
                 model with submodules, at least one sample per code path is
                 needed.
             is_qat (bool): Whether to do quantization aware training or not.
-            fold_quantize (bool): Enables or disables constant folding when quantization
-                is completed.
+            fold_quantize (bool): Enables or disables constant folding when
+                quantization is completed.
 
         Returns:
             GraphModule: The quantized model.
@@ -949,7 +959,6 @@ def _set_disallow_tfa_for_nodes(self, model: GraphModule) -> None:
         quantized models.
 
         """
-
         # First, set all nodes according to global config
         for node in model.graph.nodes:
             node.meta[DISALLOW_TFA_META_KEY] = self.global_config is None
@@ -1104,10 +1113,10 @@ def __init__(
 
     @property
     def quantizers(self) -> List[Quantizer]:
-        """Returns the configured quantizers in order of precedence, ensuring
-        the global config and shared_qspec_quantizer are applied last.
+        """Return the configured quantizers in order of precedence.
 
-        The returned list is a shallow copy; quantizer instances are shared.
+        The returned list is a shallow copy; quantizer instances are shared. The
+        global config and shared_qspec_quantizer are applied last.
 
         """
         quantizers = self._quantizers.copy()
@@ -1119,9 +1128,7 @@ def quantizers(self) -> List[Quantizer]:
 
     @quantizers.setter
     def quantizers(self, value: List[Quantizer]) -> None:
-        """Override of quantizers setter to allow for dynamic updating of
-        quantizers without accessing self._quantizers.
-        """
+        """Update quantizers without accessing self._quantizers directly."""
         self._quantizers = value
 
     def annotate(self, model):

backends/arm/tosa/partitioner.py

@@ -155,8 +155,7 @@ def reject_partition(
 
 
 def _validate_partition(nodes: set[torch.fx.Node]) -> bool:
-    """Check whether a set of nodes can be extracted as a subgraph without
-    cycles.
+    """Check whether a set of nodes can be extracted.
 
     Perform a BFS from the external users of partition nodes. If any node
     reached by BFS is itself inside the partition, then extracting the
@@ -260,9 +259,7 @@ def __init__(
         self.intermediate_path = compile_spec._get_intermediate_path()
 
     def register_custom_partition_op(self, op: torch._ops.OpOverload) -> None:
-        """Register a custom op to be considered supported by this
-        partitioner.
-        """
+        """Register a custom op to be considered supported."""
         self._custom_partition_ops.add(op)
 
     def _detag_boundary_nodes(
@@ -284,9 +281,10 @@ def _detag_boundary_nodes(
             tag: The delegation tag assigned to the partition.
             reporter: A reporter to log rejected nodes.
             module: The GraphModule containing the partition.
+            detag_first_fp_node: Whether to de-tag the first floating-point
+                node in a partition.
 
         """
-
         # De-tag outermost q-nodes upwards and dq-nodes downwards.
         # De-tag if at least one input/output is not part of the partition.
         for node in module.graph.nodes:
@@ -322,9 +320,7 @@ def _detag_boundary_nodes(
                         break
 
     def _preserve_io_quantization_enabled(self) -> bool:
-        """Return True if IO quantization should be preserved from compile
-        specs.
-        """
+        """Return True if compile specs preserve IO quantization."""
         for spec in self.delegation_spec.compile_specs:
             if spec.key != "preserve_io_quantization":
                 continue
@@ -622,9 +618,10 @@ def ops_to_not_decompose(  # noqa: C901
         }
 
         def filter_fn(node: torch.fx.Node) -> bool:
-            """Filter function applied to ops in 'ops_to_not_decompose'. Returns
-            True if the op should not be decomposed. If this function returns
-            True, the partitioner *must* accept the node, or the lowering fails.
+            """Return True if an op should not be decomposed.
+
+            If this function returns True, the partitioner *must* accept the
+            node, or the lowering fails.
 
             Args:
                 node (torch.fx.Node): FX node to evaluate.

backends/arm/vgf/backend.py

@@ -75,9 +75,11 @@ class VgfRuntimeEnvironmentCheck:
 
     @property
     def ok(self) -> bool:
+        """Return True when the check did not fail."""
         return self.status != STATUS_FAIL
 
     def to_dict(self) -> dict[str, str | None]:
+        """Return the check as a JSON-serializable dictionary."""
         return {
             "name": self.name,
             "status": self.status,
@@ -94,7 +96,6 @@ def _load_runtime() -> Any:
 
 def check_vgf_runtime_backend_environment() -> VgfRuntimeEnvironmentCheck:
     """Check whether the installed runtime exposes the VGF backend."""
-
     try:
         runtime = _load_runtime()
     except Exception as exc: