Merge pull request #61 from oesteban/docs/maintenance

DOC: Update documentation

CHANGES.rst

@@ -1,24 +1,49 @@
-0.1.3 (October 15, 2019)
-========================
+1.0.0 (November 25, 2019)
+=========================
+
+  * CI: Add check to avoid deployment of documentation from forks (#48)
+  * CI: Fix CircleCI builds by adding a [refresh workdir] commit message tag (#47)
+  * CI: Optimize CircleCI using a local docker registry instead docker save/load (#45)
+  * DOC: Fix typo and link to BIDS Specification (#49)
+  * DOC: Build API documentation (#43)
+  * ENH: Base implementation for phase1/2 fieldmaps (#60)
+  * ENH: Update ``spatialimage.get_data()`` -> ``spatialimage.get_fdata()`` (#58)
+  * ENH: Refactor fieldmap-unwarping flows, more homogeneous interface (#56)
+  * ENH: Transparency on fieldmap plots! (#57)
+  * ENH: Stop using siemens2rads from old nipype workflows (#50)
+  * ENH: Refactor the distortion estimation workflow (#53)
+  * ENH: Deduplicating magnitude handling and fieldmap postprocessing workflows (#52)
+  * ENH: Do not use legacy demean function from old nipype workflows (#51)
+  * ENH: Revise and add tests for the PEPOLAR correction (#29)
+  * ENH: Improved fieldmap reportlets (#28)
+  * ENH: Set-up testing framework (#27)
+  * MAINT: Housekeeping - flake8 errors, settings, etc. (#44)
+  * MAINT: Rename boldrefs to distortedrefs (#41)
+  * MAINT: Use niflow-nipype1-workflows for old nipype.workflows imports (#39)
+
+Pre-1.0.0 releases
+==================
+
+0.1.4 (November 22, 2019)
+-------------------------
+A maintenance release to pin niworkflows to version 1.0.0rc1.
 
-Adapts SDCflow to the separation of workflows from Nipype 1.
+0.1.3 (October 15, 2019)
+------------------------
+Adapts *SDCflows* to the separation of workflows from Nipype 1.
 
 * MAINT: pin `niflow-nipype1-workflows`, `nipype` and update corresponding imports.
 
 0.1.2 (October 10, 2019)
-========================
-
+------------------------
 BAD RELEASE -- DO NOT USE
 
 0.1.1 (July 23, 2019)
-=====================
-
+---------------------
 Minor fixup of the deploy infrastructure from CircleCI
 
 * MAINT: Add manifest including versioneer (#25) @effigies
 
 0.1.0 (July 22, 2019)
-=====================
-
-First version working with fMRIPrep v1.4.1.
-
+---------------------
+First version working with *fMRIPrep* v1.4.1.

docs/api.rst

@@ -0,0 +1,11 @@
+Library API (application program interface)
+===========================================
+
+Information on specific functions, classes, and methods.
+
+.. toctree::
+   :glob:
+
+   api/sdcflows.interfaces
+   api/sdcflows.viz
+   api/sdcflows.workflows

docs/changes.rst

@@ -0,0 +1,5 @@
+-----------
+What's new?
+-----------
+
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -89,7 +89,10 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'api/modules.rst']
+exclude_patterns = [
+    '_build', 'Thumbs.db', '.DS_Store',
+    'api/sdcflows.rst',
+    'api/sdcflows.cli.rst', 'api/sdcflows.cli.*.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None

docs/index.rst

@@ -6,4 +6,6 @@ Contents
 .. toctree::
     :maxdepth: 3
 
-    api/sdcflows
+    installation
+    api
+    changes

docs/installation.rst

@@ -0,0 +1,37 @@
+
+.. include:: links.rst
+
+Installation
+============
+
+Make sure all of *SDCflows*' `External Dependencies`_ are installed.
+These tools must be installed and their binaries available in the
+system's ``$PATH``.
+A relatively interpretable description of how your environment can be set-up
+is found in the `Dockerfile <https://github.com/poldracklab/sdcflows/blob/master/Dockerfile>`_.
+As an additional installation setting, FreeSurfer_ requires a license file.
+
+On a functional Python 3.5 (or above) environment with ``pip`` installed,
+*SDCflows* can be installed using the habitual command ::
+
+    $ python -m pip install sdcflows
+
+Check your installation with the following command line ::
+
+    $ python -c "from sdcflows import __version__; print(__version__)"
+
+
+External Dependencies
+---------------------
+
+The *SDCflows* are written using Python 3.5 (or above), and are based on
+nipype_.
+
+*SDCflows* require some other neuroimaging software tools that are
+not handled by the Python's packaging system (Pypi) used to deploy
+the ``sdcflows`` package:
+
+- FSL_ (version 5.0.9)
+- ANTs_ (version 2.2.0 - NeuroDocker build)
+- AFNI_ (version Debian-16.2.07)
+- FreeSurfer_ (version 6.0.1)

docs/links.rst

@@ -0,0 +1,8 @@
+.. _Nipype: http://nipype.readthedocs.io/en/latest/
+.. _BIDS: http://bids.neuroimaging.io
+.. _Installation: installation.html
+.. _workflows: workflows.html
+.. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/
+.. _ANTs: https://stnava.github.io/ANTs/
+.. _AFNI: https://afni.nimh.nih.gov/
+.. _FreeSurfer: https://surfer.nmr.mgh.harvard.edu/