Merge pull request #1200 from ZviBaratz/doc/docstrings

DOC: Standardize module-level docstrings format

Author: effigies

Diff for: nibabel/affines.py

@@ -1,7 +1,6 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""Utility routines for working with points and affine transforms
-"""
+"""Utility routines for working with points and affine transforms"""
 from functools import reduce
 
 import numpy as np
@@ -100,7 +99,7 @@ def apply_affine(aff, pts, inplace=False):
 
 
 def to_matvec(transform):
-    """Split a transform into its matrix and vector components.
+    """Split a transform into its matrix and vector components
 
     The transformation must be represented in homogeneous coordinates and is
     split into its rotation matrix and translation vector components.
@@ -312,8 +311,7 @@ def voxel_sizes(affine):
 
 
 def obliquity(affine):
-    r"""
-    Estimate the *obliquity* an affine's axes represent.
+    r"""Estimate the *obliquity* an affine's axes represent
 
     The term *obliquity* is defined here as the rotation of those axes with
     respect to the cardinal axes.

Diff for: nibabel/arraywriters.py

@@ -28,7 +28,6 @@ def __init__(self, array, out_dtype=None)
 something else to make sense of conversions between float and int, or between
 larger ints and smaller.
 """
-
 import numpy as np
 
 from .casting import (

Diff for: nibabel/brikhead.py

@@ -6,8 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""
-Class for reading AFNI BRIK/HEAD datasets
+"""Class for reading AFNI BRIK/HEAD datasets
 
 See https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html
 for information on what is required to have a valid BRIK/HEAD dataset.

Diff for: nibabel/data.py

@@ -1,8 +1,6 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""
-Utilities to find files from NIPY data packages
-"""
+"""Utilities to find files from NIPY data packages"""
 import configparser
 import glob
 import os

Diff for: nibabel/deprecated.py

@@ -1,5 +1,4 @@
-"""Module to help with deprecating objects and classes
-"""
+"""Module to help with deprecating objects and classes"""
 from __future__ import annotations
 
 import typing as ty

Diff for: nibabel/deprecator.py

@@ -1,5 +1,4 @@
-"""Class for recording and reporting deprecations
-"""
+"""Class for recording and reporting deprecations"""
 from __future__ import annotations
 
 import functools

Diff for: nibabel/dft.py

@@ -7,8 +7,7 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 # Copyright (C) 2011 Christian Haselgrove
-"""DICOM filesystem tools
-"""
+"""DICOM filesystem tools"""
 
 
 import contextlib

Diff for: nibabel/ecat.py

@@ -42,7 +42,6 @@
 GPL and some of the header files are adapted from CTI files (called CTI code
 below).  It's not clear what the licenses are for these files.
 """
-
 import warnings
 from numbers import Integral
 

Diff for: nibabel/environment.py

@@ -1,9 +1,6 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""
-Settings from the system environment relevant to NIPY
-"""
-
+"""Settings from the system environment relevant to NIPY"""
 import os
 from os.path import join as pjoin
 

Diff for: nibabel/eulerangles.py

@@ -82,7 +82,6 @@
 ``y``, followed by rotation around ``x``, is known (confusingly) as
 "xyz", pitch-roll-yaw, Cardan angles, or Tait-Bryan angles.
 """
-
 import math
 from functools import reduce
 

Diff for: nibabel/filebasedimages.py

@@ -6,7 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""Common interface for any image format--volume or surface, binary or xml."""
+"""Common interface for any image format--volume or surface, binary or xml"""
 from __future__ import annotations
 
 import io

Diff for: nibabel/fileholders.py

@@ -7,7 +7,6 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 """Fileholder class"""
-
 from copy import copy
 
 from .openers import ImageOpener

Diff for: nibabel/filename_parser.py

@@ -7,7 +7,6 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 """Create filename pairs, triplets etc, with expected extensions"""
-
 import os
 import pathlib
 

Diff for: nibabel/fileslice.py

@@ -1,6 +1,4 @@
-"""Utilities for getting array slices out of file-like objects
-"""
-
+"""Utilities for getting array slices out of file-like objects"""
 import operator
 from functools import reduce
 from mmap import mmap

Diff for: nibabel/fileutils.py

@@ -6,8 +6,7 @@
 #   copyright and license terms.
 #
 # ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""Utilities for reading and writing to binary file formats
-"""
+"""Utilities for reading and writing to binary file formats"""
 
 
 def read_zt_byte_strings(fobj, n_strings=1, bufsize=1024):

Diff for: nibabel/imageclasses.py

@@ -7,7 +7,6 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 """Define supported image classes and names"""
-
 from .analyze import AnalyzeImage
 from .brikhead import AFNIImage
 from .cifti2 import Cifti2Image

Diff for: nibabel/imageglobals.py

@@ -23,7 +23,6 @@
 
 Use ``logger.level = 1`` to see all messages.
 """
-
 import logging
 
 error_level = 40

Diff for: nibabel/imagestats.py

@@ -6,10 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""
-Functions for computing image statistics
-"""
-
+"""Functions for computing image statistics"""
 import numpy as np
 
 from nibabel.imageclasses import spatial_axes_first

Diff for: nibabel/loadsave.py

@@ -8,7 +8,6 @@
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 # module imports
 """Utilities to load and save image objects"""
-
 import os
 
 import numpy as np

Diff for: nibabel/mriutils.py

@@ -6,9 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""
-Utilities for calculations related to MRI
-"""
+"""Utilities for calculations related to MRI"""
 
 __all__ = ['calculate_dwell_time']
 

Diff for: nibabel/nifti2.py

@@ -12,7 +12,6 @@
 
     https://www.nitrc.org/forum/message.php?msg_id=3738
 """
-
 import numpy as np
 
 from .analyze import AnalyzeHeader

Diff for: nibabel/onetime.py

@@ -1,5 +1,4 @@
-"""
-Descriptor support for NIPY.
+"""Descriptor support for NIPY
 
 Utilities to support special Python descriptors [1,2], in particular the use of
 a useful pattern for properties we call 'one time properties'.  These are

Diff for: nibabel/openers.py

@@ -6,9 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""Context manager openers for various fileobject types
-"""
-
+"""Context manager openers for various fileobject types"""
 import gzip
 import warnings
 from bz2 import BZ2File

Diff for: nibabel/orientations.py

@@ -7,8 +7,6 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 """Utilities for calculating and applying affine orientations"""
-
-
 import numpy as np
 import numpy.linalg as npl
 

Diff for: nibabel/parrec.py

@@ -8,7 +8,7 @@
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 # Disable line length checking for PAR fragments in module docstring
 # flake8: noqa E501
-"""Read images in PAR/REC format.
+"""Read images in PAR/REC format
 
 This is yet another MRI image format generated by Philips scanners. It is an
 ASCII header (PAR) plus a binary blob (REC).
@@ -121,7 +121,6 @@
 utility via the option "--strict-sort".  The dimension info can be exported
 to a CSV file by adding the option "--volume-info".
 """
-
 import re
 import warnings
 from collections import OrderedDict

Diff for: nibabel/processing.py

@@ -6,15 +6,16 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""Image processing functions for:
+"""Image processing functions
 
-* smoothing
-* resampling
-* converting sd to and from FWHM
+Image processing functions for:
 
-Smoothing and resampling routines need scipy
-"""
+    * smoothing
+    * resampling
+    * converting SD to and from FWHM
 
+Smoothing and resampling routines need scipy.
+"""
 import numpy as np
 import numpy.linalg as npl
 

Diff for: nibabel/quaternions.py

@@ -7,7 +7,7 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 """
-Functions to operate on, or return, quaternions.
+Functions to operate on, or return, quaternions
 
 The module also includes functions for the closely related angle, axis
 pair as a specification for rotation.
@@ -25,7 +25,6 @@
 >>> vec = np.array([1, 2, 3]).reshape((3,1)) # column vector
 >>> tvec = np.dot(M, vec)
 """
-
 import math
 
 import numpy as np

Diff for: nibabel/rstutils.py

@@ -2,7 +2,6 @@
 
 * Make ReST table given array of values
 """
-
 import numpy as np
 
 

Diff for: nibabel/spaces.py

@@ -19,7 +19,6 @@
   mapping), or
 * a length 2 sequence with the same information (shape, affine).
 """
-
 from itertools import product
 
 import numpy as np

Diff for: nibabel/tmpdirs.py

@@ -6,8 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""Contexts for *with* statement providing temporary directories
-"""
+"""Contexts for *with* statement providing temporary directories"""
 import os
 import tempfile
 from contextlib import contextmanager

Diff for: nibabel/tripwire.py

@@ -1,5 +1,4 @@
-"""Class to raise error for missing modules or other misfortunes
-"""
+"""Class to raise error for missing modules or other misfortunes"""
 from typing import Any
 
 

Diff for: nibabel/viewers.py

@@ -3,7 +3,6 @@
 Includes version of OrthoSlicer3D code originally written by our own
 Paul Ivanov.
 """
-
 import weakref
 
 import numpy as np
@@ -14,7 +13,7 @@
 
 
 class OrthoSlicer3D:
-    """Orthogonal-plane slice viewer.
+    """Orthogonal-plane slice viewer
 
     OrthoSlicer3d expects 3- or 4-dimensional array data.  It treats
     4D data as a sequence of 3D spatial volumes, where a slice over the final

Diff for: nibabel/xmlutils.py

@@ -6,10 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""
-Thin layer around xml.etree.ElementTree, to abstract nibabel xml support.
-"""
-
+"""Thin layer around xml.etree.ElementTree, to abstract nibabel xml support"""
 from io import BytesIO
 from xml.etree.ElementTree import Element, SubElement, tostring  # noqa
 from xml.parsers.expat import ParserCreate