Merge pull request #608 from dbic/bf-docs

DOC: Various fixes to make RTD build the docs again

Author: yarikoptic

.readthedocs.yaml

@@ -8,7 +8,7 @@ python:
 build:
   os: ubuntu-20.04
   tools:
-    python: "3"
+    python: "3.9"
 sphinx:
   configuration: docs/conf.py
   fail_on_warning: true

README.rst

@@ -54,7 +54,7 @@ Please file issues and suggest changes via Pull Requests.
 
 HeuDiConv requires installation of
 `dcm2niix <https://github.com/rordenlab/dcm2niix/>`_ and optionally
-`DataLad <https://datalad.org>`_.
+`DataLad`_.
 
 For development you will need a non-shallow clone (so there is a
 recent released tag) of the aforementioned repository. You can then

docs/changes.rst

@@ -2,4 +2,4 @@
 Changes
 =======
 
-.. mdinclude:: ../CHANGELOG.md
+.. literalinclude:: ../CHANGELOG.md

docs/conf.py

@@ -22,7 +22,7 @@
 from heudiconv import __version__
 
 project = 'heudiconv'
-copyright = '2019, Heudiconv team'
+copyright = '2014-2022, Heudiconv team'
 author = 'Heudiconv team'
 
 # The short X.Y version
@@ -43,7 +43,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinxarg.ext',
-    'm2r',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -63,7 +63,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -90,7 +90,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/requirements.txt

@@ -1,3 +1,3 @@
 sphinx-argparse
-m2r
+sphinxcontrib-napoleon
 -r ../dev-requirements.txt

heudiconv/bids.py

@@ -1,5 +1,7 @@
 """Handle BIDS specific operations"""
 
+__docformat__ = "numpy"
+
 import hashlib
 import os
 import os.path as op
@@ -157,12 +159,12 @@ def populate_bids_templates(path, defaults={}):
 
 
 def populate_aggregated_jsons(path):
-    """Aggregate across the entire BIDS dataset .json's into top level .json's
+    """Aggregate across the entire BIDS dataset ``.json``\s into top level ``.json``\s
 
     Top level .json files would contain only the fields which are
-    common to all subject[/session]/type/*_modality.json's.
+    common to all ``subject[/session]/type/*_modality.json``\s.
 
-    ATM aggregating only for *_task*_bold.json files. Only the task- and
+    ATM aggregating only for ``*_task*_bold.json`` files. Only the task- and
     OPTIONAL _acq- field is retained within the aggregated filename.  The other
     BIDS _key-value pairs are "aggregated over".
 
@@ -415,15 +417,14 @@ def save_scans_key(item, bids_files):
 
 
 def add_rows_to_scans_keys_file(fn, newrows):
-    """
-    Add new rows to file fn for scans key filename and generate accompanying json
-    descriptor to make BIDS validator happy.
+    """Add new rows to the _scans file.
 
     Parameters
     ----------
-    fn: filename
-    newrows: extra rows to add
-        dict fn: [acquisition time, referring physician, random string]
+    fn: str
+      filename
+    newrows: dict
+      extra rows to add (acquisition time, referring physician, random string)
     """
     if op.lexists(fn):
         with open(fn, 'r') as csvfile:
@@ -527,11 +528,11 @@ def get_shim_setting(json_file):
     Gets the "ShimSetting" field from a json_file.
     If no "ShimSetting" present, return error
 
-    Parameters:
+    Parameters
     ----------
     json_file : str
 
-    Returns:
+    Returns
     -------
     str with "ShimSetting" value
     """
@@ -552,13 +553,13 @@ def find_fmap_groups(fmap_dir):
     By groups here we mean fmaps that are intended to go together
     (with reversed PE polarity, magnitude/phase, etc.)
 
-    Parameters:
+    Parameters
     ----------
     fmap_dir : str or os.path
         path to the session folder (or to the subject folder, if there are no
         sessions).
 
-    Returns:
+    Returns
     -------
     fmap_groups : dict
         key: prefix common to the group (e.g. no "dir" entity, "_phase"/"_magnitude", ...)
@@ -598,14 +599,14 @@ def get_key_info_for_fmap_assignment(json_file, matching_parameter):
     (Note: It is the responsibility of the calling function to make sure
     the arguments are OK)
 
-    Parameters:
+    Parameters
     ----------
     json_file : str or os.path
         path to the json file
     matching_parameter : str in AllowedFmapParameterMatching
         matching_parameter that will be used to match runs
 
-    Returns:
+    Returns
     -------
     key_info : dict
         part of the json file that will need to match between the fmap and
@@ -666,7 +667,7 @@ def find_compatible_fmaps_for_run(json_file, fmap_groups, matching_parameters):
     (Note: It is the responsibility of the calling function to make sure
     the arguments are OK)
 
-    Parameters:
+    Parameters
     ----------
     json_file : str or os.path
         path to the json file
@@ -676,7 +677,7 @@ def find_compatible_fmaps_for_run(json_file, fmap_groups, matching_parameters):
     matching_parameters : list of str from AllowedFmapParameterMatching
         matching_parameters that will be used to match runs
 
-    Returns:
+    Returns
     -------
     compatible_fmap_groups : dict
         Subset of the fmap_groups which match json_file, according
@@ -720,15 +721,15 @@ def find_compatible_fmaps_for_session(path_to_bids_session, matching_parameters)
     (Note: It is the responsibility of the calling function to make sure
     the arguments are OK)
 
-    Parameters:
+    Parameters
     ----------
     path_to_bids_session : str or os.path
         path to the session folder (or to the subject folder, if there are no
         sessions).
     matching_parameters : list of str from AllowedFmapParameterMatching
         matching_parameters that will be used to match runs
 
-    Returns:
+    Returns
     -------
     compatible_fmap : dict
         Dict of compatible_fmaps_groups (values) for each non-fmap run (keys)
@@ -768,7 +769,7 @@ def select_fmap_from_compatible_groups(json_file, compatible_fmap_groups, criter
     (Note: It is the responsibility of the calling function to make sure
     the arguments are OK)
 
-    Parameters:
+    Parameters
     ----------
     json_file : str or os.path
         path to the json file
@@ -777,7 +778,7 @@ def select_fmap_from_compatible_groups(json_file, compatible_fmap_groups, criter
     criterion : str in ['First', 'Closest']
         matching_parameters that will be used to decide which fmap to use
 
-    Returns:
+    Returns
     -------
     selected_fmap_key : str or os.path
         key from the compatible_fmap_groups for the selected fmap group
@@ -859,7 +860,7 @@ def populate_intended_for(path_to_bids_session, matching_parameters, criterion):
     Because fmaps come in groups (with reversed PE polarity, or magnitude/
     phase), we work with fmap_groups.
 
-    Parameters:
+    Parameters
     ----------
     path_to_bids_session : str or os.path
         path to the session folder (or to the subject folder, if there are no

heudiconv/convert.py

@@ -1,3 +1,5 @@
+__docformat__ = "numpy"
+
 import filelock
 import os
 import os.path as op
@@ -453,23 +455,6 @@ def convert(items, converter, scaninfo_suffix, custom_callable, with_prov,
             dcmconfig=None, populate_intended_for_opts={}):
     """Perform actual conversion (calls to converter etc) given info from
     heuristic's `infotodict`
-
-    Parameters
-    ----------
-    items
-    symlink
-    converter
-    scaninfo_suffix
-    custom_callable
-    with_prov
-    is_bids
-    sourcedir
-    outdir
-    min_meta
-
-    Returns
-    -------
-    None
     """
     prov_files = []
     tempdirs = TempDirs()
@@ -624,10 +609,6 @@ def convert_dicom(item_dicoms, bids_options, prefix,
         Create softlink to DICOMs - if False, create hardlink instead.
     overwrite : bool
         If True, allows overwriting of previous conversion
-
-    Returns
-    -------
-    None
     """
     if bids_options is not None:
         # mimic the same hierarchy location as the prefix
@@ -666,18 +647,18 @@ def nipype_convert(item_dicoms, prefix, with_prov, bids_options, tmpdir, dcmconf
 
     Parameters
     ----------
-    item_dicoms : List
+    item_dicoms : list
         DICOM files to convert
-    prefix : String
+    prefix : str
         Heuristic output path
-    with_prov : Bool
+    with_prov : bool
         Store provenance information
-    bids_options : List or None
+    bids_options : list or None
         If not None then output BIDS sidecar JSONs
         List may contain bids specific options
-    tmpdir : Directory
+    tmpdir : str
         Conversion working directory
-    dcmconfig : File (optional)
+    dcmconfig : str, optional
         JSON file used for additional Dcm2niix configuration
     """
     import nipype
@@ -723,18 +704,19 @@ def nipype_convert(item_dicoms, prefix, with_prov, bids_options, tmpdir, dcmconf
 
 def save_converted_files(res, item_dicoms, bids_options, outtype, prefix, outname_bids, overwrite):
     """Copy converted files from tempdir to output directory.
+
     Will rename files if necessary.
 
     Parameters
     ----------
     res : Node
         Nipype conversion Node with results
-    item_dicoms: list of filenames
-        DICOMs converted
+    item_dicoms: list
+        Filenames of converted DICOMs
     bids : list or None
         If not list save to BIDS
         List may contain bids specific options
-    prefix : string
+    prefix : str
 
     Returns
     -------
@@ -877,15 +859,13 @@ def save_converted_files(res, item_dicoms, bids_options, outtype, prefix, outnam
     return bids_outfiles
 
 
-def  add_taskname_to_infofile(infofiles):
+def add_taskname_to_infofile(infofiles):
     """Add the "TaskName" field to json files corresponding to func images.
 
     Parameters
     ----------
-    infofiles : list with json filenames or single filename
-
-    Returns
-    -------
+    infofiles: list or str
+        json filenames or a single filename.
     """
 
     # in case they pass a string with a path:
@@ -908,15 +888,15 @@ def  add_taskname_to_infofile(infofiles):
 
 def bvals_are_zero(bval_file):
     """Checks if all entries in a bvals file are zero (or 5, for Siemens files).
-    Returns True if that is the case, otherwise returns False
 
     Parameters
     ----------
-    bval_file : file with the bvals
+    bval_file : str
+      file with the bvals
 
     Returns
     -------
-    True if all are zero; False otherwise.
+    True if all are all 0 or 5; False otherwise.
     """
 
     with open(bval_file) as f:

heudiconv/parser.py

@@ -29,6 +29,7 @@
 def find_files(regex, topdir=op.curdir, exclude=None,
                exclude_vcs=True, dirs=False):
     """Generator to find files matching regex
+
     Parameters
     ----------
     regex: basestring
@@ -60,7 +61,8 @@ def find_files(regex, topdir=op.curdir, exclude=None,
 
 
 def get_extracted_dicoms(fl):
-    """Given a list of files, possibly extract some from tarballs
+    """Given a list of files, possibly extract some from tarballs.
+
     For 'classical' heudiconv, if multiple tarballs are provided, they correspond
     to different sessions, so here we would group into sessions and return
     pairs  `sessionid`, `files`  with `sessionid` being None if no "sessions"
@@ -116,13 +118,15 @@ def get_extracted_dicoms(fl):
 
 def get_study_sessions(dicom_dir_template, files_opt, heuristic, outdir,
                        session, sids, grouping='studyUID'):
-    """Given options from cmdline sort files or dicom seqinfos into
-    study_sessions which put together files for a single session of a subject
-    in a study
-    Two major possible workflows:
+    """Sort files or dicom seqinfos into study_sessions.
+
+    study_sessions put together files for a single session of a subject
+    in a study.  Two major possible workflows:
+
     - if dicom_dir_template provided -- doesn't pre-load DICOMs and just
       loads files pointed by each subject and possibly sessions as corresponding
-      to different tarballs
+      to different tarballs.
+
     - if files_opt is provided, sorts all DICOMs it can find under those paths
     """
     study_sessions = {}