Merge pull request #1989 from oesteban/docs/intersphinx

DOC: Integrate intersphinx, drop external module wrapping

Author: oesteban

docs/api.rst

@@ -0,0 +1,11 @@
+.. include:: links.rst
+
+================
+Developers - API
+================
+
+Workflows
+---------
+
+.. automodule:: fmriprep.workflows.base
+.. automodule:: fmriprep.workflows.bold

docs/api/index.rst

@@ -21,83 +21,83 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.append(os.path.abspath('sphinxext'))
-sys.path.insert(0, os.path.abspath('../wrapper'))
+sys.path.append(os.path.abspath("sphinxext"))
+sys.path.insert(0, os.path.abspath("../wrapper"))
 
 from github_link import make_linkcode_resolve
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.5.3'
+needs_sphinx = "1.5.3"
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.linkcode',
-    'sphinxarg.ext',  # argparse extension
-    'nipype.sphinxext.plot_workflow',
-    'nbsphinx',
-    'sphinxcontrib.napoleon',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.linkcode",
+    "sphinxarg.ext",  # argparse extension
+    "nipype.sphinxext.plot_workflow",
+    "nbsphinx",
+    "sphinxcontrib.napoleon",
 ]
 
 # Mock modules in autodoc:
 autodoc_mock_imports = [
-    'numpy',
-    'nitime',
-    'matplotlib',
+    "numpy",
+    "nitime",
+    "matplotlib",
 ]
 
-if pver.parse(sphinxversion) >= pver.parse('1.7.0'):
+if pver.parse(sphinxversion) >= pver.parse("1.7.0"):
     autodoc_mock_imports += [
-        'pandas',
-        'nilearn',
-        'seaborn',
+        "pandas",
+        "nilearn",
+        "seaborn",
     ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # Accept custom section names to be parsed for numpy-style docstrings
 # of parameters.
 # Requires pinning sphinxcontrib-napoleon to a specific commit while
 # https://github.com/sphinx-contrib/napoleon/pull/10 is merged.
 napoleon_use_param = False
 napoleon_custom_sections = [
-    ('Inputs', 'Parameters'),
-    ('Outputs', 'Parameters'),
+    ("Inputs", "Parameters"),
+    ("Outputs", "Parameters"),
 ]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+# source_suffix = [".rst", ".md"]
+source_suffix = ".rst"
 
 # The encoding of source files.
-# source_encoding = 'utf-8-sig'
+# source_encoding = "utf-8-sig"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'fmriprep'
-author = 'The fMRIPrep developers'
-copyright = '2016-%s, %s' % (datetime.now().year, author)
+project = "fmriprep"
+author = "The fMRIPrep developers"
+copyright = "2016-%s, %s" % (datetime.now().year, author)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'version'
+version = "version"
 # The full version, including alpha/beta/rc tags.
-release = u'version'
+release = "version"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -115,7 +115,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -133,7 +133,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -149,7 +149,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -178,7 +178,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 = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -243,7 +243,7 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'fmriprepdoc'
+htmlhelp_basename = "fmriprepdoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -265,9 +265,9 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'fmriprep.tex', u'fMRIprep Documentation',
+    (master_doc, "fmriprep.tex", "fMRIprep Documentation",
      author,
-     'manual'),
+     "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -296,7 +296,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'fmriprep', u'fmriprep Documentation',
+    (master_doc, "fmriprep", "fmriprep Documentation",
      [author], 1)
 ]
 
@@ -310,9 +310,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'fmriprep', u'fMRIprep Documentation',
-     author, 'fmriprep', 'One line description of project.',
-     'Miscellaneous'),
+    (master_doc, "fmriprep", "fMRIprep Documentation",
+     author, "fmriprep", "One line description of project.",
+     "Miscellaneous"),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -328,18 +328,30 @@
 # texinfo_no_detailmenu = False
 
 # The following is used by sphinx.ext.linkcode to provide links to github
-linkcode_resolve = make_linkcode_resolve('fmriprep',
-                                         u'https://github.com/poldracklab/'
-                                         'fmriprep/blob/{revision}/'
-                                         '{package}/{path}#L{lineno}')
+linkcode_resolve = make_linkcode_resolve("fmriprep",
+                                         "https://github.com/poldracklab/"
+                                         "fmriprep/blob/{revision}/"
+                                         "{package}/{path}#L{lineno}")
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "numpy": ("http://docs.scipy.org/doc/numpy", None),
+    "scipy": ("http://docs.scipy.org/doc/scipy/reference", None),
+    "matplotlib": ("http://matplotlib.sourceforge.net", None),
+    "bids": ("https://bids-standard.github.io/pybids/", None),
+    "nibabel": ("https://nipy.org/nibabel/", None),
+    "nipype": ("https://nipype.readthedocs.io/en/latest/", None),
+    "niworkflows": ("https://poldracklab.github.io/niworkflows/", None),
+    "sdcflows": ("https://www.nipreps.org/sdcflows/", None),
+    "smriprep": ("https://poldracklab.github.io/smriprep/", None),
+    "templateflow": ("https://www.templateflow.org/python-client", None),
+}
 
 suppress_warnings = ["image.nonlocal_uri"]
 
 
 def setup(app):
-    app.add_stylesheet('theme_overrides.css')
+    app.add_stylesheet("theme_overrides.css")
     # We need this for the boilerplate script
     app.add_javascript("https://cdn.rawgit.com/chrisfilo/zenodo.js/v0.1/zenodo.js")

docs/conf.py

@@ -25,5 +25,5 @@ Contents
    faq
    contributors
    citing
-   api/index.rst
+   api
    changes

docs/index.rst

@@ -19,4 +19,6 @@
 .. _`Docker Hub`: https://hub.docker.com/r/poldracklab/fmriprep/tags
 .. _Singularity: https://github.com/singularityware/singularity
 ..  _SPM: https://www.fil.ion.ucl.ac.uk/spm/software/spm12/
-.. _TACC: https://www.tacc.utexas.edu/
+.. _TACC: https://www.tacc.utexas.edu/
+.. _tedana: https://github.com/me-ica/tedana
+.. _`T2* workflow`: https://tedana.readthedocs.io/en/latest/generated/tedana.workflows.t2smap_workflow.html#tedana.workflows.t2smap_workflow  # noqa

docs/links.rst

@@ -2,10 +2,15 @@
 
 Susceptibility Distortion Correction (SDC)
 ------------------------------------------
+Please note that all routines for susceptibility-derived distortion correction
+have been excised off of *fMRIPrep* for utilization on other projects
+(e.g., `dMRIPrep <https://www.nipreps.org/dmriprep>`__).
+For more detailed documentation on
+:abbr:`SDC (susceptibility-derived distortion correction)`
+routines, check on `www.nipreps.org/sdcflows <https://www.nipreps.org/sdcflows>`__.
 
 Introduction
 ~~~~~~~~~~~~
-
 :abbr:`SDC (susceptibility-derived distortion correction)` methods usually try to
 make a good estimate of the field inhomogeneity map.
 The inhomogeneity map is directly related to the displacement of
@@ -21,72 +26,62 @@ as follows ([Jezzard1995]_, [Hutton2002]_):
 
       d_\text{PE}(x, y, z) = \gamma \Delta B_0(x, y, z) T_\text{ro} \qquad (1)
 
-
-where :math:`\gamma` is the gyromagnetic ratio. Therefore, the
-displacements map :math:`d_\text{PE}(x, y, z)` can be estimated
-either via estimating the inhomogeneity map :math:`\Delta B_0(x, y, z)`
-(:ref:`sdc_phasediff` and :ref:`sdc_direct_b0`) or
-via image registration (:ref:`sdc_pepolar`, :ref:`sdc_fieldmapless`).
-
+where :math:`\gamma` is the gyromagnetic ratio.
+Therefore, the displacements map :math:`d_\text{PE}(x, y, z)` can be estimated
+either via estimating the inhomogeneity map :math:`\Delta B_0(x, y, z)` or
+via image registration (see below).
 
 Correction methods
 ~~~~~~~~~~~~~~~~~~
-
 The are five broad families of methodologies for mapping the field:
 
-  1. :ref:`sdc_pepolar` (also called **blip-up/blip-down**):
+  1. **Phase Encoding POLARity** (*PEPOLAR*; also called *blip-up/blip-down*;
+     :py:func:`~sdcflows.workflows.pepolar.init_pepolar_unwarp_wf`):
      acquire at least two images with varying :abbr:`PE (phase-encoding)` directions.
      Hence, the realization of distortion is different between the different
      acquisitions. The displacements map :math:`d_\text{PE}(x, y, z)` is
      estimated with an image registration process between the different
      :abbr:`PE (phase-encoding)` acquisitions, regularized by the
      readout time :math:`T_\text{ro}`.
      Corresponds to 8.9.4 of BIDS.
-
-  2. :ref:`sdc_direct_b0`: some sequences (such as :abbr:`SE (spiral echo)`)
+  2. **Direct B0 mapping sequences** (:py:func:`~sdcflows.workflows.fmap.init_fmap_wf`):
+     some sequences (such as :abbr:`SE (spiral echo)`)
      are able to measure the fieldmap :math:`\Delta B_0(x, y, z)` directly.
      Corresponds to section 8.9.3 of BIDS.
-
-  3. :ref:`sdc_phasediff`: to estimate the fieldmap :math:`\Delta B_0(x, y, z)`,
+  3. **Phase-difference B0 mapping** (:py:func:`~sdcflows.workflows.phdiff.init_phdiff_wf`):
+     to estimate the fieldmap :math:`\Delta B_0(x, y, z)`,
      these methods   measure the phase evolution in time between two close
      :abbr:`GRE (Gradient Recall Echo)` acquisitions. Corresponds to the sections
      8.9.1 and 8.9.2 of the BIDS specification.
-
-  4. :ref:`sdc_fieldmapless`: FMRIPREP now experimentally supports displacement
+  4. **"Fieldmap-less" estimation** (experimental; :py:func:`~sdcflows.workflows.syn.init_syn_sdc_wf`):
+     *fMRIPrep* now experimentally supports displacement
      field estimation in the absence of fieldmaps via nonlinear registration.
-
-  5. **Point-spread function acquisition**: Not supported by FMRIPREP.
-
+  5. **Point-spread function acquisition**: Not supported by BIDS, and hence *fMRIPrep*.
 
 In order to select the appropriate estimation workflow, the input BIDS dataset is
-first queried to find the available field-mapping techniques (see :ref:`sdc_base`).
+first queried to find the available field-mapping techniques
+(see :py:func:`~sdcflows.workflows.base.init_sdc_estimate_wf`).
 Once the field-map (or the corresponding displacement field) is estimated, the
-distortion can be accounted for (see :ref:`sdc_unwarp`).
-
-
+distortion can be accounted for 
+(see :py:func:`~sdcflows.workflows.unwarp.init_sdc_unwarp_wf`).
 
 Calculating the effective echo-spacing and total-readout time
 .............................................................
-
 To solve :ref:`(1) <eq_fieldmap>`, all methods (with the exception of the
 fieldmap-less approach) will require information about the in-plane
 speed of the :abbr:`EPI (echo-planar imaging)` scheme used in
 acquisition by reading either the :math:`T_\text{ro}`
-(total-readout time) or :math:`t_\text{ees}` (effective echo-spacing):
-
-.. autofunction:: fmriprep.interfaces.fmap.get_ees
-.. autofunction:: fmriprep.interfaces.fmap.get_trt
+(total-readout time) or :math:`t_\text{ees}` (effective echo-spacing).
+See corresponding implementations under *SDCFlows*:
 
+  * :py:func:`~sdcflows.interfaces.fmap.get_ees`
+  * :py:func:`~sdcflows.interfaces.fmap.get_trt`
 
 From the phase-difference map to a field map
 ............................................
-
 To solve :ref:`(1) <eq_fieldmap>` using a :ref:`phase-difference map <sdc_phasediff>`,
 the field map :math:`\Delta B_0(x, y, z)` can be derived from the phase-difference
-map:
-
-.. autofunction:: fmriprep.interfaces.fmap.phdiff2fmap
-
+map (:py:func:`~sdcflows.interfaces.fmap.phdiff2fmap`)
 
 References
 ..........
@@ -95,3 +90,6 @@ References
                  Correction for geometric distortion in echo planar images from B0
                  field variations Magn. Reson. Med., 34 (1) (1995), pp. 65-73,
                  doi:`10.1002/mrm.1910340111 <https://doi.org/10.1002/mrm.1910340111>`_.
+.. [Hutton2002] Hutton et al., Image Distortion Correction in fMRI: A Quantitative
+                Evaluation, NeuroImage 16(1):217-240, 2002. doi:`10.1006/nimg.2001.1054
+                <https://doi.org/10.1006/nimg.2001.1054>`_.