Merge pull request #398 from PennLINC/small-module-docstrings

Add module docstrings for __about__.py, __init__.py, constants.py, and utils.py

cubids/__about__.py

@@ -1,6 +1,25 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""Base module variables."""
+"""Base module variables for CuBIDS.
+
+This module defines the base variables for the CuBIDS package, including version,
+package name, copyright, credits, and URLs.
+
+Attributes
+----------
+__version__ : str
+    The version of the CuBIDS package.
+__packagename__ : str
+    The name of the CuBIDS package.
+__copyright__ : str
+    The copyright information for the CuBIDS package.
+__credits__ : str
+    The credits for the CuBIDS package.
+__url__ : str
+    The URL for the CuBIDS package repository.
+DOWNLOAD_URL : str
+    The URL to download the CuBIDS package.
+"""
 try:
     from cubids._version import __version__
 except ImportError:

cubids/__init__.py

@@ -1,4 +1,37 @@
-"""Top-level package for CuBIDS."""
+"""Top-level package for CuBIDS.
+
+This module initializes the CuBIDS package and imports its main submodules and attributes.
+
+Submodules
+----------
+cli : module
+    Command-line interface for CuBIDS.
+config : module
+    Configuration utilities for CuBIDS.
+constants : module
+    Constants used throughout the CuBIDS package.
+cubids : module
+    Core functionalities of the CuBIDS package.
+metadata_merge : module
+    Utilities for merging metadata in CuBIDS.
+utils : module
+    Utility functions for CuBIDS.
+validator : module
+    Validation utilities for CuBIDS.
+workflows : module
+    Workflows for CuBIDS operations.
+
+Attributes
+----------
+__version__ : str
+    The version of the CuBIDS package.
+__packagename__ : str
+    The name of the CuBIDS package.
+__copyright__ : str
+    The copyright information for the CuBIDS package.
+__credits__ : str
+    The credits for the CuBIDS package.
+"""
 
 from cubids import (
     cli,

cubids/constants.py

@@ -1,14 +1,21 @@
-"""Constants for CuBIDS."""
+"""Constants for CuBIDS.
+
+This module defines various constants used throughout the CuBIDS package.
+
+Attributes
+----------
+ID_VARS : set of str
+    Names of identifier variables. Used to place EntitySet and ParamGroup at
+    the beginning of a dataframe but both are hardcoded in the relevant function.
+NON_KEY_ENTITIES : set of str
+    Entities that should not be used to group parameter sets.
+IMAGING_PARAMS : set of str
+    List of metadata fields merged in `metadata_merge.py`.
+"""
 
-# Names of identifier variables.
-# Used to place EntitySet and ParamGroup at the beginning of a dataframe,
-# but both are hardcoded in the relevant function.
 ID_VARS = set(["EntitySet", "ParamGroup", "FilePath"])
-# Entities that should not be used to group parameter sets
 NON_KEY_ENTITIES = set(["subject", "session", "extension"])
 # Multi-dimensional keys SliceTiming  XXX: what is this line about?
-# List of metadata fields and parameters (calculated by CuBIDS)
-# Not sure what this specific list is used for.
 IMAGING_PARAMS = set(
     [
         "ParallelReductionFactorInPlane",

cubids/utils.py

@@ -1,4 +1,7 @@
-"""Miscellaneous utility functions for CuBIDS."""
+"""Miscellaneous utility functions for CuBIDS.
+
+This module provides various utility functions used throughout the CuBIDS package.
+"""
 
 import re
 from pathlib import Path