Add pydoc with ruff check that public classes should have documentati…

…on. (#1034)

Co-authored-by: Paul Adkisson <[email protected]>

CHANGELOG.md

@@ -7,6 +7,7 @@
 ### Bug fixes
 
 ### Improvements
+* Using ruff to enforce existence of public classes' docstrings [PR #1034](https://github.com/catalystneuro/neuroconv/pull/1034)
 
 ## v0.6.1 (August 30, 2024)
 
@@ -54,6 +55,7 @@
 
 
 
+
 ## v0.5.0 (July 17, 2024)
 
 ### Deprecations

pyproject.toml

@@ -123,20 +123,21 @@ extend-exclude = '''
 
 
 [tool.ruff]
-exclude = [
-  "*/__init__.py"
-]
 
 [tool.ruff.lint]
-select = ["F401", "I"]  # TODO: eventually, expand to other 'F' linting
+select = ["F401", "I", "D101"] # TODO: eventually, expand to other 'F' linting
 fixable = ["ALL"]
 
+[tool.ruff.lint.per-file-ignores]
+"**__init__.py" = ["F401", "I"]
+"tests/**" = ["D"]  # We are not enforcing docstrings in tests
+"src/neuroconv/tools/testing/data_interface_mixins.py" = ["D"]  # We are not enforcing docstrings in the interface mixings
+
 [tool.ruff.lint.isort]
 relative-imports-order = "closest-to-furthest"
 known-first-party = ["neuroconv"]
 
 
-
 [tool.codespell]
 skip = '.git*,*.pdf,*.css'
 check-hidden = true

src/neuroconv/datainterfaces/ecephys/axona/axonadatainterface.py

@@ -132,6 +132,9 @@ def __init__(self, file_path: FilePath, noise_std: float = 3.5):
 
 
 class AxonaLFPDataInterface(BaseLFPExtractorInterface):
+    """
+    Primary data interface class for converting Axona LFP data.
+    """
 
     display_name = "Axona LFP"
     associated_suffixes = (".bin", ".set")

src/neuroconv/datainterfaces/ecephys/cellexplorer/cellexplorerdatainterface.py

@@ -361,6 +361,14 @@ def get_original_timestamps(self):
 
 
 class CellExplorerLFPInterface(CellExplorerRecordingInterface):
+    """
+    Adds lfp data from binary files with the new CellExplorer format:
+
+    https://cellexplorer.org/
+
+    See the `CellExplorerRecordingInterface` class for more information.
+    """
+
     display_name = "CellExplorer LFP"
     keywords = BaseRecordingExtractorInterface.keywords + (
         "extracellular electrophysiology",

src/neuroconv/datainterfaces/ecephys/neuralynx/neuralynxdatainterface.py

@@ -94,6 +94,11 @@ def get_metadata(self) -> dict:
 
 
 class NeuralynxSortingInterface(BaseSortingExtractorInterface):
+    """
+    Primary data interface for converting Neuralynx sorting data. Uses
+    :py:class:`~spikeinterface.extractors.NeuralynxSortingExtractor`.
+    """
+
     display_name = "Neuralynx Sorting"
     associated_suffixes = (".nse", ".ntt", ".nse", ".nev")
     info = "Interface for Neuralynx sorting data."

src/neuroconv/datainterfaces/ecephys/spikeglx/spikeglxdatainterface.py

@@ -17,6 +17,10 @@
 
 
 class SpikeGLXRecordingInterface(BaseRecordingExtractorInterface):
+    """
+    Primary SpikeGLX interface for converting raw SpikeGLX data using a :py:class:`~spikeinterface.extractors.SpikeGLXRecordingExtractor`.
+    """
+
     display_name = "SpikeGLX Recording"
     keywords = BaseRecordingExtractorInterface.keywords + ("Neuropixels",)
     associated_suffixes = (".imec{probe_index}", ".ap", ".lf", ".meta", ".bin")

src/neuroconv/datainterfaces/ophys/brukertiff/brukertiffconverter.py

@@ -13,6 +13,10 @@
 
 
 class BrukerTiffMultiPlaneConverter(NWBConverter):
+    """
+    Converter class for Bruker imaging data with multiple channels and multiple planes.
+    """
+
     display_name = "Bruker TIFF Imaging (multiple channels, multiple planes)"
     keywords = BrukerTiffMultiPlaneImagingInterface.keywords
     associated_suffixes = BrukerTiffMultiPlaneImagingInterface.associated_suffixes
@@ -123,6 +127,10 @@ def run_conversion(
 
 
 class BrukerTiffSinglePlaneConverter(NWBConverter):
+    """
+    Primary data interface class for converting Bruker imaging data with multiple channels and a single plane.
+    """
+
     display_name = "Bruker TIFF Imaging (multiple channels, single plane)"
     keywords = BrukerTiffMultiPlaneImagingInterface.keywords
     associated_suffixes = BrukerTiffMultiPlaneImagingInterface.associated_suffixes

src/neuroconv/tools/hdmf.py

@@ -7,7 +7,9 @@
 from hdmf.data_utils import GenericDataChunkIterator as HDMFGenericDataChunkIterator
 
 
-class GenericDataChunkIterator(HDMFGenericDataChunkIterator):
+class GenericDataChunkIterator(HDMFGenericDataChunkIterator):  # noqa: D101
+    # TODO Should this be added to the API?
+
     def _get_default_buffer_shape(self, buffer_gb: float = 1.0) -> tuple[int]:
         return self.estimate_default_buffer_shape(
             buffer_gb=buffer_gb, chunk_shape=self.chunk_shape, maxshape=self.maxshape, dtype=self.dtype

src/neuroconv/tools/path_expansion.py

@@ -13,6 +13,15 @@
 
 
 class AbstractPathExpander(abc.ABC):
+    """
+    Abstract base class for expanding file paths and extracting metadata.
+
+    This class provides methods to extract metadata from file paths within a directory
+    and to expand paths based on a specified data specification. It is designed to be
+    subclassed, with the `list_directory` method needing to be implemented by any
+    subclass to provide the specific logic for listing files in a directory.
+    """
+
     def extract_metadata(self, base_directory: DirectoryPath, format_: str):
         """
         Uses the parse library to extract metadata from file paths in the base_directory.
@@ -128,7 +137,13 @@ def expand_paths(self, source_data_spec: dict[str, dict]) -> list[DeepDict]:
 
 
 class LocalPathExpander(AbstractPathExpander):
-    def list_directory(self, base_directory: DirectoryPath) -> Iterable[FilePath]:
+    """
+    Class for expanding file paths and extracting metadata on a local filesystem.
+
+    See https://neuroconv.readthedocs.io/en/main/user_guide/expand_path.html for more information.
+    """
+
+    def list_directory(self, base_directory: DirectoryPath) -> Iterable[FilePath]:  # noqa: D101
         base_directory = Path(base_directory)
         assert base_directory.is_dir(), f"The specified 'base_directory' ({base_directory}) is not a directory!"
         return (str(path.relative_to(base_directory)) for path in base_directory.rglob("*"))

src/neuroconv/tools/testing/data_interface_mixins.py

@@ -767,6 +767,10 @@ def test_interface_alignment(self, setup_interface):
 
 
 class AudioInterfaceTestMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixin for testing Audio interfaces.
+    """
+
     # Currently asserted in the downstream testing suite; could be refactored in future PR
     def check_read_nwb(self, nwbfile_path: str):
         pass
@@ -777,6 +781,10 @@ def test_interface_alignment(self):
 
 
 class DeepLabCutInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixin for testing DeepLabCut interfaces.
+    """
+
     def check_interface_get_original_timestamps(self):
         pass  # TODO in separate PR
 
@@ -797,6 +805,10 @@ def check_nwbfile_temporal_alignment(self):
 
 
 class VideoInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixin for testing Video interfaces.
+    """
+
     def check_read_nwb(self, nwbfile_path: str):
         with NWBHDF5IO(path=nwbfile_path, mode="r", load_namespaces=True) as io:
             nwbfile = io.read()
@@ -867,6 +879,10 @@ def check_interface_original_timestamps_inmutability(self):
 
 
 class MedPCInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixin for testing MedPC interfaces.
+    """
+
     def check_no_metadata_mutation(self, metadata: dict):
         """Ensure the metadata object was not altered by `add_to_nwbfile` method."""
 
@@ -1101,6 +1117,10 @@ def test_interface_alignment(self, medpc_name_to_info_dict: dict):
 
 
 class MiniscopeImagingInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixin for testing Miniscope Imaging interfaces.
+    """
+
     def check_read_nwb(self, nwbfile_path: str):
         from ndx_miniscope import Miniscope
 
@@ -1129,6 +1149,10 @@ def check_read_nwb(self, nwbfile_path: str):
 
 
 class ScanImageSinglePlaneImagingInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixing for testing ScanImage Single Plane Imaging interfaces.
+    """
+
     def check_read_nwb(self, nwbfile_path: str):
         with NWBHDF5IO(nwbfile_path, "r") as io:
             nwbfile = io.read()
@@ -1160,6 +1184,10 @@ def check_read_nwb(self, nwbfile_path: str):
 
 
 class ScanImageMultiPlaneImagingInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """
+    A mixin for testing ScanImage MultiPlane Imaging interfaces.
+    """
+
     def check_read_nwb(self, nwbfile_path: str):
         with NWBHDF5IO(nwbfile_path, "r") as io:
             nwbfile = io.read()
@@ -1190,6 +1218,8 @@ def check_read_nwb(self, nwbfile_path: str):
 
 
 class TDTFiberPhotometryInterfaceMixin(DataInterfaceTestMixin, TemporalAlignmentMixin):
+    """Mixin for testing TDT Fiber Photometry interfaces."""
+
     def check_no_metadata_mutation(self, metadata: dict):
         """Ensure the metadata object was not altered by `add_to_nwbfile` method."""
 

src/neuroconv/tools/testing/mock_interfaces.py

@@ -18,6 +18,10 @@
 
 
 class MockBehaviorEventInterface(BaseTemporalAlignmentInterface):
+    """
+    A mock behavior event interface for testing purposes.
+    """
+
     @classmethod
     def get_source_schema(cls) -> dict:
         source_schema = get_schema_from_method_signature(method=cls.__init__, exclude=["event_times"])
@@ -56,6 +60,10 @@ def add_to_nwbfile(self, nwbfile: NWBFile, metadata: dict):
 
 
 class MockSpikeGLXNIDQInterface(SpikeGLXNIDQInterface):
+    """
+    A mock SpikeGLX interface for testing purposes.
+    """
+
     ExtractorName = "NumpyRecording"
 
     @classmethod
@@ -150,6 +158,10 @@ def get_metadata(self) -> dict:
 
 
 class MockImagingInterface(BaseImagingExtractorInterface):
+    """
+    A mock imaging interface for testing purposes.
+    """
+
     def __init__(
         self,
         num_frames: int = 30,

src/neuroconv/utils/json_schema.py

@@ -17,7 +17,17 @@
 
 
 class NWBMetaDataEncoder(json.JSONEncoder):
+    """
+    Custom JSON encoder for NWB metadata.
+
+    This encoder extends the default JSONEncoder class and provides custom serialization
+    for certain data types commonly used in NWB metadata.
+    """
+
     def default(self, obj):
+        """
+        Serialize custom data types to JSON. This overwrites the default method of the JSONEncoder class.
+        """
         # Over-write behaviors for datetime object
         if isinstance(obj, datetime):
             return obj.isoformat()
@@ -34,6 +44,12 @@ def default(self, obj):
 
 
 class NWBSourceDataEncoder(NWBMetaDataEncoder):
+    """
+    Custom JSON encoder for data interface source data (i.e. kwargs).
+
+    This encoder extends the default JSONEncoder class and provides custom serialization
+    for certain data types commonly used in interface source data.
+    """
 
     def default(self, obj):