🎨 Standardize docstring format across changes.

Author: shnizzedy

CPAC/pipeline/engine/nodeblock.py

@@ -14,7 +14,7 @@
 
 # You should have received a copy of the GNU Lesser General Public
 # License along with C-PAC. If not, see <https://www.gnu.org/licenses/>.
-"""Class and decorator for NodeBlock functions."""
+"""Classes and decorator for :py:class:`NodeBlock`\u200bs and :py:class:`NodeBlockFunction`\u200bs."""
 
 from typing import Any, Callable, Optional, TYPE_CHECKING
 
@@ -50,32 +50,37 @@ def __init__(
         outputs: Optional[NODEBLOCK_OUTPUTS] = None,
     ) -> None:
         self.func = func
-        """Nodeblock function reference."""
+        """`Nodeblock` function reference."""
         self.name: str = name
-        """Used in the graph and logging to identify the NodeBlock and its component nodes."""
+        """Used in the graph and logging to identify the :py:class:`NodeBlock` and its component :py:class:`~nipype.pipeline.engine.Node`\u200bs."""
         self.config: Optional[list[str]] = config
         """
-        Indicates the nested keys in a C-PAC pipeline configuration should configure a NodeBlock built from this
-        function. If config is set to ``None``, then all other configuration-related entities must be specified from the
+        Indicates the nested keys in a C-PAC pipeline :py:class:`Configuration`
+        should configure a `NodeBlock` built from this function. If `config` is set to
+        `None`, then all other configuration-related entities must be specified from the
         root of the configuration.
         """
         self.switch: Optional[list[str] | list[list[str]]] = switch
         """
-        Indicates any keys that should evaluate to True for this NodeBlock to be active. A list of lists of strings
-        indicates multiple switches that must all be True to run, and is currently only an option if config is set to
-        ``None``.
+        Indicates any keys that should evaluate to `True` for this :py:class:`NodeBlock`
+        to be active. A list of lists of strings indicates multiple `switch`\u200bes
+        that must all be `True` to run, and is currently only an option if `config` is
+        set to `None`.
         """
         self.option_key: Optional[str | list[str]] = option_key
         """
-        Indicates the nested keys (starting at the nested key indicated by config) that should configure this NodeBlock.
+        Indicates the nested keys (starting at the nested key indicated by `config`)
+        that should configure this :py:class:`NodeBlock`.
         """
         self.option_val: Optional[str | list[str]] = option_val
-        """Indicates values for which this NodeBlock should be active."""
+        """Indicates values for which this :py:class:`NodeBlock` should be active."""
         self.inputs: list[str | list | tuple] = inputs if inputs else []
-        """ResourcePool keys indicating resources needed for the NodeBlock's functionality."""
+        """:py:class:`~CPAC.pipeline.engine.resource.ResourcePool` keys indicating
+        resources needed for the :py:class:`NodeBlock`\u200b's functionality."""
         self.outputs: list[str] | dict[str, Any] = outputs if outputs else []
         """
-        ResourcePool keys indicating resources generated or updated by the NodeBlock, optionally including metadata
+        :py:class:`~CPAC.pipeline.engine.resource.ResourcePool` keys indicating
+        resources generated or updated by the `NodeBlock`, optionally including metadata
         for the outputs' respective sidecars.
         """
 
@@ -101,14 +106,14 @@ def __call__(
         pipe_num: Optional[int | str],
         opt: Optional[str] = None,
     ) -> tuple[Workflow, dict[str, "ResourceData"]]:
-        """Call a NodeBlockFunction.
+        """Call a `NodeBlockFunction`.
 
-        All node block functions have the same signature.
+        All `NodeBlockFunction`\u200bs have the same signature.
         """
         return self.func(wf, cfg, strat_pool, pipe_num, opt)
 
     def legacy_nodeblock_dict(self):
-        """Return nodeblock metadata as a dictionary.
+        """Return :py:class:`NodeBlock` metadata as a dictionary.
 
         Helper for compatibility reasons.
         """
@@ -123,7 +128,7 @@ def legacy_nodeblock_dict(self):
         }
 
     def __repr__(self) -> str:
-        """Return reproducible string representation of a NodeBlockFunction."""
+        """Return reproducible string representation of a `NodeBlockFunction`."""
         return (
             f"NodeBlockFunction({self.func.__module__}."
             f'{self.func.__name__}, "{self.name}", '
@@ -134,19 +139,19 @@ def __repr__(self) -> str:
         )
 
     def __str__(self) -> str:
-        """Return string representation of a NodeBlockFunction."""
+        """Return string representation of a `NodeBlockFunction`."""
         return f"NodeBlockFunction({self.name})"
 
 
 class NodeBlock:
-    """A worflow subgraph composed of :py:class:`NodeBlockFunction`s."""
+    """A :py:class:`Workflow` subgraph composed of :py:class:`NodeBlockFunction`\u200bs."""
 
     def __init__(
         self,
         node_block_functions: NodeBlockFunction | PIPELINE_BLOCKS,
         debug: bool = False,
     ) -> None:
-        """Create a ``NodeBlock`` from a list of py:class:`~CPAC.pipeline.engine.nodeblock.NodeBlockFunction`s."""
+        """Create a `NodeBlock` from a list of py:class:`NodeBlockFunction`\u200bs."""
         if not isinstance(node_block_functions, list):
             node_block_functions = [node_block_functions]
 
@@ -218,9 +223,12 @@ def __init__(
                 logging.update_logging(config)
 
     def check_output(self, outputs: NODEBLOCK_OUTPUTS, label: str, name: str) -> None:
-        """Check if a label is listed in a NodeBlock's ``outputs``.
+        """Check if a label is listed in a `NodeBlock`\u200b's `outputs`.
 
-        Raises ``NameError`` if a mismatch is found.
+        Raises
+        ------
+        NameError
+            If a mismatch is found.
         """
         if label not in outputs:
             msg = (
@@ -234,13 +242,20 @@ def check_output(self, outputs: NODEBLOCK_OUTPUTS, label: str, name: str) -> Non
     def list_blocks(
         pipeline_blocks: PIPELINE_BLOCKS, indent: Optional[int] = None
     ) -> str:
-        """List node blocks line by line.
+        """List :py:class:`NodeBlockFunction`\u200bs line by line.
 
         Parameters
         ----------
-        pipeline_blocks: list of :py:class:`NodeBlockFunction`s
+        pipeline_blocks
+            list of :py:class:`NodeBlockFunction`\u200bs
 
-        indent: number of spaces after a tab indent
+        indent
+            number of spaces after a tab indent
+
+        Returns
+        -------
+        str
+            formatted list of :py:class:`NodeBlockFunction`\u200bs
         """
         blockstring = yaml.dump(
             [
@@ -277,26 +292,46 @@ def nodeblock(
     inputs: Optional[NODEBLOCK_INPUTS] = None,
     outputs: Optional[list[str] | dict[str, Any]] = None,
 ):
-    """
-    Define a node block.
+    """Define a :py:class:`NodeBlockFunction`\u200b.
 
-    Connections to the pipeline configuration and to other node blocks.
+    Connections to the pipeline :py:class:`Configuration` and to other :py:class:`NodeBlockFunction`\u200bs.
 
     Parameters
     ----------
-    name: Used in the graph and logging to identify the NodeBlock and its component nodes. Function's ``.__name__`` is used if ``name`` is not provided.
-
-    config: Indicates the nested keys in a C-PAC pipeline configuration should configure a NodeBlock built from this function. If config is set to ``None``, then all other configuration-related entities must be specified from the root of the configuration.
-
-    switch: Indicates any keys that should evaluate to True for this NodeBlock to be active. A list of lists of strings indicates multiple switches that must all be True to run, and is currently only an option if config is set to ``None``.
-
-    option_key: Indicates the nested keys (starting at the nested key indicated by config) that should configure this NodeBlock.
-
-    option_val: Indicates values for which this NodeBlock should be active.
-
-    inputs: ResourcePool keys indicating files needed for the NodeBlock's functionality.
-
-    outputs: ResourcePool keys indicating files generated or updated by the NodeBlock, optionally including metadata for the outputs' respective sidecars.
+    name
+        Used in the graph and logging to identify the :py:class:`NodeBlock` and its
+        component :py:class:`~nipype.pipeline.engine.Node`\u200bs.
+        The :py:class:`NodeBlockFunction`\u200b's `.__name__` is used if `name` is not
+        provided.
+
+    config
+        Indicates the nested keys in a C-PAC pipeline :py:class:`Configuration` should
+        configure a :py:class:`NodeBlock` built from this
+        :py:class:`NodeBlockFunction`\u200b. If `config` is set to `None`, then all other
+        :py:class:`Configuration`\u200b-related entities must be specified from the root
+        of the :py:class:`Configuration`\u200b.
+
+    switch
+        Indicates any keys that should evaluate to `True` for this :py:class:`NodeBlock`
+        to be active. A list of lists of strings indicates multiple switches that must
+        all be `True` to run, and is currently only an option if config is set to
+        `None`.
+
+    option_key
+        Indicates the nested keys (starting at the nested key indicated by `config`)
+        that should configure this :py:class:`NodeBlock`\u200b.
+
+    option_val
+        Indicates values for which this :py:class:`NodeBlock` should be active.
+
+    inputs
+        ResourcePool keys indicating files needed for the :py:class:`NodeBlock`\u200b's
+        functionality.
+
+    outputs
+        :py:class:`~CPAC.pipeline.engine.resource.ResourcePool` keys indicating files
+        generated or updated by the :py:class:`NodeBlock`, optionally including metadata
+        for the outputs' respective sidecars.
     """
     return lambda func: NodeBlockFunction(
         func,