DOC: Address warnings and improve formatting

Author: effigies

nibabel/affines.py

@@ -306,7 +306,7 @@ def obliquity(affine):
     This implementation is inspired by `AFNI's implementation
     <https://github.com/afni/afni/blob/b6a9f7a21c1f3231ff09efbd861f8975ad48e525/src/thd_coords.c#L660-L698>`_.
     For further details about *obliquity*, check `AFNI's documentation
-    <https://sscc.nimh.nih.gov/sscc/dglen/Obliquity>_.
+    <https://sscc.nimh.nih.gov/sscc/dglen/Obliquity>`_.
 
     Parameters
     ----------

nibabel/brikhead.py

@@ -250,7 +250,7 @@ def __init__(self, file_like, header, mmap=True, keep_file_open=None):
             a new file handle is created every time the image is accessed.
             If ``file_like`` refers to an open file handle, this setting has no
             effect. The default value (``None``) will result in the value of
-            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT` being used.
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
         """
         super(AFNIArrayProxy, self).__init__(file_like,
                                              header,
@@ -533,7 +533,7 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             a new file handle is created every time the image is accessed.
             If ``file_like`` refers to an open file handle, this setting has no
             effect. The default value (``None``) will result in the value of
-            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT` being used.
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
         """
         with file_map['header'].get_prepare_fileobj('rt') as hdr_fobj:
             hdr = klass.header_class.from_fileobj(hdr_fobj)
@@ -553,6 +553,7 @@ def filespec_to_file_map(klass, filespec):
         afni.nimh.nih.gov/pub/dist/doc/program_help/README.compression.html.
         Thus, if you have AFNI files my_image.HEAD and my_image.BRIK.gz and you
         want to load the AFNI BRIK / HEAD pair, you can specify:
+
             * The HEAD filename - e.g., my_image.HEAD
             * The BRIK filename w/o compressed extension - e.g., my_image.BRIK
             * The full BRIK filename - e.g., my_image.BRIK.gz

nibabel/cifti2/__init__.py

@@ -26,4 +26,4 @@
                      Cifti2TransformationMatrixVoxelIndicesIJKtoXYZ,
                      Cifti2Vertices, Cifti2Volume, CIFTI_BRAIN_STRUCTURES,
                      Cifti2HeaderError, CIFTI_MODEL_TYPES, load, save)
-from .cifti2_axes import (Axis, BrainModelAxis, ParcelsAxis, SeriesAxis, LabelAxis, ScalarAxis)
+from .cifti2_axes import (Axis, BrainModelAxis, ParcelsAxis, SeriesAxis, LabelAxis, ScalarAxis)

nibabel/cifti2/cifti2.py

@@ -172,7 +172,7 @@ def _to_xml_element(self):
 
 
 class Cifti2LabelTable(xml.XmlSerializable, MutableMapping):
-    """ CIFTI-2 label table: a sequence of ``Cifti2Label``s
+    """ CIFTI-2 label table: a sequence of ``Cifti2Label``\s
 
     * Description - Used by NamedMap when IndicesMapToDataType is
       "CIFTI_INDEX_TYPE_LABELS" in order to associate names and display colors
@@ -927,8 +927,8 @@ class Cifti2MatrixIndicesMap(xml.XmlSerializable, MutableSequence):
     * Text Content: [NA]
     * Parent Element - Matrix
 
-    Attribute
-    ---------
+    Attributes
+    ----------
     applies_to_matrix_dimension : list of ints
         Dimensions of this matrix that follow this mapping
     indices_map_to_data_type : str one of CIFTI_MAP_TYPES

nibabel/cifti2/cifti2_axes.py

@@ -23,7 +23,7 @@
 (except for SeriesAxis objects, which have to remain monotonically increasing or decreasing).
 
 Creating new CIFTI-2 axes
------------------------
+-------------------------
 New Axis objects can be constructed by providing a description for what is contained
 in each row/column of the described tensor. For each Axis sub-class this descriptor is:
 
@@ -250,7 +250,7 @@ def __init__(self, name, voxel=None, vertex=None, affine=None,
         factory methods:
 
         - :py:meth:`~BrainModelAxis.from_mask`: creates surface or volumetric BrainModelAxis axis
-        from respectively 1D or 3D masks
+          from respectively 1D or 3D masks
         - :py:meth:`~BrainModelAxis.from_surface`: creates a surface BrainModelAxis axis
 
         The resulting BrainModelAxis axes can be concatenated by adding them together.

nibabel/gifti/gifti.py

@@ -207,18 +207,21 @@ class GiftiCoordSystem(xml.XmlSerializable):
     Attributes
     ----------
     dataspace : int
-        From the spec: "Contains the stereotaxic space of a DataArray's data
+        From the spec: Contains the stereotaxic space of a DataArray's data
         prior to application of the transformation matrix. The stereotaxic
         space should be one of:
-            NIFTI_XFORM_UNKNOWN
-            NIFTI_XFORM_SCANNER_ANAT
-            NIFTI_XFORM_ALIGNED_ANAT
-            NIFTI_XFORM_TALAIRACH
-            NIFTI_XFORM_MNI_152"
+
+          - NIFTI_XFORM_UNKNOWN
+          - NIFTI_XFORM_SCANNER_ANAT
+          - NIFTI_XFORM_ALIGNED_ANAT
+          - NIFTI_XFORM_TALAIRACH
+          - NIFTI_XFORM_MNI_152
+
     xformspace : int
         Spec: "Contains the stereotaxic space of a DataArray's data after
         application of the transformation matrix. See the DataSpace element for
         a list of stereotaxic spaces."
+
     xform : array-like shape (4, 4)
         Affine transformation matrix
     """

nibabel/nifti1.py

@@ -1775,18 +1775,18 @@ def __init__(self, dataobj, affine, header=None,
             self._affine2header()
     # Copy docstring
     __init__.__doc__ = analyze.AnalyzeImage.__init__.__doc__ + '''
-    Notes
-    -----
-
-    If both a `header` and an `affine` are specified, and the `affine` does
-    not match the affine that is in the `header`, the `affine` will be used,
-    but the ``sform_code`` and ``qform_code`` fields in the header will be
-    re-initialised to their default values. This is performed on the basis
-    that, if you are changing the affine, you are likely to be changing the
-    space to which the affine is pointing.  The :meth:`set_sform` and
-    :meth:`set_qform` methods can be used to update the codes after an image
-    has been created - see those methods, and the :ref:`manual
-    <default-sform-qform-codes>` for more details.  '''
+        Notes
+        -----
+
+        If both a `header` and an `affine` are specified, and the `affine` does
+        not match the affine that is in the `header`, the `affine` will be used,
+        but the ``sform_code`` and ``qform_code`` fields in the header will be
+        re-initialised to their default values. This is performed on the basis
+        that, if you are changing the affine, you are likely to be changing the
+        space to which the affine is pointing.  The :meth:`set_sform` and
+        :meth:`set_qform` methods can be used to update the codes after an image
+        has been created - see those methods, and the :ref:`manual
+        <default-sform-qform-codes>` for more details.  '''
 
     def update_header(self):
         ''' Harmonize header with image data and affine

nibabel/streamlines/tck.py

@@ -30,20 +30,18 @@ class TckFile(TractogramFile):
     -----
     MRtrix (so its file format: TCK) considers streamlines coordinates
     to be in world space (RAS+ and mm space). MRtrix refers to that space
-    as the "real" or "scanner" space [1]_.
+    as the "real" or "scanner" space [#]_.
 
-    Moreover, when streamlines are mapped back to voxel space [2]_, a
+    Moreover, when streamlines are mapped back to voxel space [#]_, a
     streamline point located at an integer coordinate (i,j,k) is considered
     to be at the center of the corresponding voxel. This is in contrast with
     TRK's internal convention where it would have referred to a corner.
 
     NiBabel's streamlines internal representation follows the same
     convention as MRtrix.
 
-    References
-    ----------
-    [1] http://www.nitrc.org/pipermail/mrtrix-discussion/2014-January/000859.html
-    [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
+    .. [#] http://www.nitrc.org/pipermail/mrtrix-discussion/2014-January/000859.html
+    .. [#] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
     """
     # Constants
     MAGIC_NUMBER = "mrtrix tracks"

nibabel/streamlines/tractogram.py

@@ -263,9 +263,9 @@ class Tractogram(object):
     choice as long as you provide the correct `affine_to_rasmm` matrix, at
     construction time. When applied to streamlines coordinates, that
     transformation matrix should bring the streamlines back to world space
-    (RAS+ and mm space) [1]_.
+    (RAS+ and mm space) [#]_.
 
-    Moreover, when streamlines are mapped back to voxel space [2]_, a
+    Moreover, when streamlines are mapped back to voxel space [#]_, a
     streamline point located at an integer coordinate (i,j,k) is considered
     to be at the center of the corresponding voxel. This is in contrast with
     other conventions where it might have referred to a corner.
@@ -292,8 +292,8 @@ class Tractogram(object):
 
     References
     ----------
-    [1] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces
-    [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
+    .. [#] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces
+    .. [#] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
     """
     def __init__(self, streamlines=None,
                  data_per_streamline=None,
@@ -515,9 +515,9 @@ class LazyTractogram(Tractogram):
     choice as long as you provide the correct `affine_to_rasmm` matrix, at
     construction time. When applied to streamlines coordinates, that
     transformation matrix should bring the streamlines back to world space
-    (RAS+ and mm space) [1]_.
+    (RAS+ and mm space) [#]_.
 
-    Moreover, when streamlines are mapped back to voxel space [2]_, a
+    Moreover, when streamlines are mapped back to voxel space [#]_, a
     streamline point located at an integer coordinate (i,j,k) is considered
     to be at the center of the corresponding voxel. This is in contrast with
     other conventions where it might have referred to a corner.
@@ -553,8 +553,8 @@ class LazyTractogram(Tractogram):
 
     References
     ----------
-    [1] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces
-    [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
+    .. [#] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces
+    .. [#] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
     """
     def __init__(self, streamlines=None,
                  data_per_streamline=None,