Ensure all exposed classes are documented (#363)

Enable the `pydocstyle` pre-commit hook, and fix / add all reported docstrings.

Add `FeFormat`, `IgnorableEntity` and `PuckMaterialType` enums to the list of
public classes.

Note: there is no explicit automated check that all exposed objects are included in the 
documentation's `.rst` files.

.pre-commit-config.yaml

@@ -37,11 +37,12 @@ repos:
         name: "poetry: check poetry.lock consistency"
         args: ["--lock"]
         files: '^(pyproject\.toml|poetry\.lock)$'
-  # - repo: https://github.com/pycqa/pydocstyle
-  #   rev: 6.1.1
-  #   hooks:
-  #   - id: pydocstyle
-  #     additional_dependencies: [toml]
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 6.1.1
+    hooks:
+    - id: pydocstyle
+      additional_dependencies: [toml]
+      exclude: "^(tests/)|(type_checks/)|(examples/)"
   - repo: https://github.com/kynan/nbstripout
     rev: 0.6.1
     hooks:

doc/source/api/other_types.rst

@@ -16,14 +16,17 @@ Other data types
     EdgeSetType
     EdgeSetType
     ElementalDataType
+    FeFormat
     FieldVariable
     GeometricalRuleType
+    IgnorableEntity
     InterpolationOptions
     LookUpTable3DInterpolationAlgorithm
     LookUpTableColumnValueType
     NodalDataType
     PlyCutoffType
     PlyType
+    PuckMaterialType
     RosetteSelectionMethod
     SensorType
     StatusType

pyproject.toml

@@ -127,7 +127,7 @@ src_paths = ["doc", "src", "tests"]
 
 [tool.pydocstyle]
 convention = "numpy"
-add-ignore = "D201,D202,D203,D204" # blank line rules before / after docstring
+add-ignore = "D201,D202,D203,D204,D105" # blank line rules before / after docstring; magic methods
 
 [tool.codespell]
 skip = '*.cdb,*.dat'

src/ansys/acp/core/__init__.py

@@ -1,3 +1,8 @@
+"""PyACP: Ansys Composite PrepPost (ACP) module for Python.
+
+PyACP enables you to design and analyze layered composite structures.
+"""
+
 import importlib.metadata
 
 from ._model_printer import get_model_tree, print_model
@@ -42,11 +47,13 @@
     ElementSetNodalData,
     Fabric,
     FabricWithAngle,
+    FeFormat,
     FieldVariable,
     GeometricalRuleType,
     GeometricalSelectionRule,
     GeometricalSelectionRuleElementalData,
     GeometricalSelectionRuleNodalData,
+    IgnorableEntity,
     InterpolationOptions,
     Lamina,
     LinkedSelectionRule,
@@ -76,6 +83,7 @@
     ProductionPly,
     ProductionPlyElementalData,
     ProductionPlyNodalData,
+    PuckMaterialType,
     Rosette,
     RosetteSelectionMethod,
     ScalarData,
@@ -165,6 +173,7 @@
     "ExampleKeys",
     "Fabric",
     "FabricWithAngle",
+    "FeFormat",
     "FieldVariable",
     "GeometricalRuleType",
     "GeometricalSelectionRule",
@@ -174,6 +183,7 @@
     "get_dpf_unit_system",
     "get_example_file",
     "get_model_tree",
+    "IgnorableEntity",
     "InterpolationOptions",
     "Lamina",
     "launch_acp",
@@ -206,6 +216,7 @@
     "ProductionPly",
     "ProductionPlyElementalData",
     "ProductionPlyNodalData",
+    "PuckMaterialType",
     "Rosette",
     "RosetteSelectionMethod",
     "ScalarData",

src/ansys/acp/core/_model_printer.py

@@ -50,7 +50,6 @@ def _add_tree_part(
 def print_model(model: Model) -> None:
     """Print a tree representation of the model.
 
-
     Parameters
     ----------
     model:

src/ansys/acp/core/_server/acp_instance.py

@@ -165,9 +165,9 @@ def clear(self) -> None:
 
     @property
     def models(self) -> tuple[Model, ...]:
-        """The models currently loaded on the server.
+        """Models currently loaded on the server.
 
-        Note that the models are returned in arbitrary order.
+        Note that the models are listed in arbitrary order.
         """
         model_stub = model_pb2_grpc.ObjectServiceStub(self._channel)
         return tuple(

src/ansys/acp/core/_tree_objects/__init__.py

@@ -69,6 +69,7 @@
     FieldVariable,
     InterpolationOptions,
     Material,
+    PuckMaterialType,
     VariableDensity,
     VariableEngineeringConstants,
     VariableFabricFiberAngle,
@@ -80,7 +81,7 @@
     VariableWovenCharacterization,
     VariableWovenStressLimits,
 )
-from .model import Model, ModelElementalData, ModelNodalData
+from .model import FeFormat, IgnorableEntity, Model, ModelElementalData, ModelNodalData
 from .modeling_group import ModelingGroup
 from .modeling_ply import ModelingPly, ModelingPlyElementalData, ModelingPlyNodalData, TaperEdge
 from .oriented_selection_set import (
@@ -155,11 +156,13 @@
     "ElementSetNodalData",
     "Fabric",
     "FabricWithAngle",
+    "FeFormat",
     "FieldVariable",
     "GeometricalRuleType",
     "GeometricalSelectionRule",
     "GeometricalSelectionRuleElementalData",
     "GeometricalSelectionRuleNodalData",
+    "IgnorableEntity",
     "InterpolationOptions",
     "Lamina",
     "LinkedSelectionRule",
@@ -172,11 +175,11 @@
     "Material",
     "Model",
     "ModelElementalData",
-    "ModelNodalData",
     "ModelingGroup",
     "ModelingPly",
     "ModelingPlyElementalData",
     "ModelingPlyNodalData",
+    "ModelNodalData",
     "NodalDataType",
     "OrientedSelectionSet",
     "OrientedSelectionSetElementalData",
@@ -189,6 +192,7 @@
     "ProductionPly",
     "ProductionPlyElementalData",
     "ProductionPlyNodalData",
+    "PuckMaterialType",
     "Rosette",
     "RosetteSelectionMethod",
     "ScalarData",

src/ansys/acp/core/_tree_objects/_grpc_helpers/edge_property_list.py

@@ -42,11 +42,10 @@ def _set_callback_apply_changes(self, callback_apply_changes: Callable[[], None]
 
 
 class EdgePropertyList(MutableSequence[ValueT]):
-    """
-    The edge property list is used to wrap graph edges of a specific type.
+    """Wrap graph edges of a specific type.
 
-    For instance FabricWithAngle of a stackup.
-    This object handles the conversion of the protobuf messages to the
+    Wraps links between objects of a specific type, for instance FabricWithAngle
+    of a stackup. This object handles the conversion of the protobuf messages to the
     corresponding Python object and vice-versa.
     self._object_list holds the Python object. The python objects are stored
     to support editing in-place editing. This is achieved by passing a callback
@@ -163,42 +162,99 @@ def __contains__(self, item: object) -> bool:
         return item in self._object_list
 
     def append(self, value: ValueT) -> None:
+        """Append an object to the list.
+
+        Parameters
+        ----------
+        value :
+            The object to append.
+        """
         obj_list = self._object_list
         obj_list.append(value)
         self._set_object_list(obj_list)
 
     def count(self, value: ValueT) -> int:
+        """Count the number of occurrences of an object in the list.
+
+        Parameters
+        ----------
+        value : ValueT
+            The object to count.
+        """
         return self._object_list.count(value)
 
     def index(self, value: ValueT, start: int = 0, stop: int = sys.maxsize) -> int:
+        """Return the index of the first occurrence of an object in the list.
+
+        Parameters
+        ----------
+        value :
+            The object to search for.
+        start :
+            The index to start searching from.
+        stop :
+            The index to stop searching at.
+        """
         return self._object_list.index(value, start, stop)
 
     def extend(self, iterable: Iterable[ValueT]) -> None:
+        """Extend the list by appending all the items from the iterable.
+
+        Parameters
+        ----------
+        iterable :
+            The iterable to append.
+        """
         obj_list = self._object_list
         obj_list.extend([it for it in iterable])
         self._set_object_list(obj_list)
 
     def insert(self, index: int, value: ValueT) -> None:
+        """Insert an object at a given position.
+
+        Parameters
+        ----------
+        index :
+            The index to insert at.
+        value :
+            The object to insert.
+        """
         obj_list = self._object_list
         obj_list.insert(index, value)
         self._set_object_list(obj_list)
 
     def pop(self, index: int = -1) -> ValueT:
+        """Remove and return the object at the given index.
+
+        Parameters
+        ----------
+        index :
+            The index of the object to remove.
+        """
         obj_list = self._object_list
         obj = obj_list.pop(index)
         self._set_object_list(obj_list)
         return obj
 
     def remove(self, value: ValueT) -> None:
+        """Remove the first occurrence of an object from the list.
+
+        Parameters
+        ----------
+        value :
+            The object to remove.
+        """
         obj_list = self._object_list
         obj_list.remove(value)
         self._set_object_list(obj_list)
 
     def reverse(self) -> None:
+        """Reverse the list in-place."""
         self._set_object_list(list(reversed(self._object_list)))
 
     def _apply_changes(self) -> None:
-        """
+        """Apply changes to the list.
+
         Use to support in-place modification.
         This function applies the changes if someone edits one entry of the list.
         """
@@ -230,6 +286,8 @@ def __repr__(self) -> str:
 def define_edge_property_list(
     attribute_name: str, value_type: type[GenericEdgePropertyType], doc: str | None = None
 ) -> Any:
+    """Define a list of linked tree objects with link properties."""
+
     def getter(self: CreatableTreeObject) -> EdgePropertyList[GenericEdgePropertyType]:
         return EdgePropertyList(
             parent_object=self,

src/ansys/acp/core/_tree_objects/_grpc_helpers/enum_wrapper.py

@@ -20,6 +20,7 @@ def wrap_to_string_enum(
     Values of the enum are the keys, converted to lowercase.
 
     Returns
+    -------
     :
         A tuple containing
         - the string enum

src/ansys/acp/core/_tree_objects/_grpc_helpers/linked_object_helpers.py

@@ -18,7 +18,8 @@ def unlink_objects(pb_object: Message) -> None:
 def linked_path_fields(
     pb_object: Message,
 ) -> Iterable[tuple[Message, FieldDescriptor, Union[ResourcePath, CollectionPath]]]:
-    """
+    """Get all linked paths from a protobuf object.
+
     Get tuples (parent_message, field_descriptor, {resource_path or collection_path})
     describing all resource or collection paths present in the protobuf
     object.