enh: clean up documentation

- point to michael's tutorials
- reorganize display of workflows and interfaces

Author: satra

doc/documentation.rst

@@ -11,8 +11,13 @@ Documentation
 
 Previous versions:  `0.12.0 <http://nipype.readthedocs.io/en/0.12.0/>`_ `0.11.0 <http://nipy.org/nipype/0.11.0>`_
 
+
 .. container:: doc2
 
+  .. admonition:: Michael Notter's Nipype guide
+
+    Be sure to read `Michael's excellent tutorials <https://miykael.github.io/nipype_tutorial/>`_.
+
   .. admonition:: Guides
 
     .. hlist::

doc/links_names.txt

@@ -74,8 +74,7 @@
 .. _pythonxy: https://python-xy.github.io/
 .. _EPD: http://www.enthought.com/products/epd.php
 .. _Traits: http://code.enthought.com/projects/traits/
-.. _Anaconda: https://www.continuum.io/downloads
-.. _Canopy: https://www.enthought.com/products/canopy/
+.. _Miniconda: https://conda.io/miniconda.html
 
 .. Python imaging projects
 .. _PyMVPA: http://www.pymvpa.org

doc/quickstart.rst

@@ -11,34 +11,30 @@ Downloading and installing
    :maxdepth: 1
 
    users/install
-   users/vagrant
 
 Beginner's guide
 ================
 
-Beginner's tutorials (IPython Notebooks). `Available here`__
+Michael Notter's Nipype tutorial. `Available here`__
 
-Michael Notter's Nipype guide. `Available here`__
+__ https://miykael.github.io/nipype_tutorial/
 
-Dissecting Nipype Workflows. `Available here`__
+Nipype workshop materials
+=========================
 
-Introductory slides [older]. `Available here`__
+Self-assessment questionnaire with links to learning about each piece. `Available here`__
 
-__ https://github.com/mwaskom/nipype_concepts
-__ http://miykael.github.com/nipype-beginner-s-guide/index.html
-__ http://slideviewer.herokuapp.com/url/raw.github.com/nipy/nipype/master/examples/nipype_tutorial.ipynb?theme=sky
-__ http://satra.github.com/intro2nipype
+Lecture slides `Available here`__
 
-User guides
-===========
+__ http://nipy.org/workshops/2017-03-boston/review.html
+__ http://nipy.org/workshops/2017-03-boston/index.html
 
-.. toctree::
-   :maxdepth: 1
+`Docker containers <https://hub.docker.com/r/nipype/workshops/tags/>`_
+
+`Github project for lectures <https://github.com/nipy/workshops/tree/gh-pages/2017-03-boston>`_
+`Github project for dockerfiles + notebooks <https://github.com/nipy/workshops/tree/master/170327-nipype>`_
 
-   users/interface_tutorial
-   users/pipeline_tutorial
-   users/plugins
-   users/debug
+`All notebooks visualized <http://nbviewer.jupyter.org/github/nipy/workshops/tree/master/170327-nipype/notebooks/>`_
 
 Developer guides
 ================
@@ -47,16 +43,6 @@ Developer guides
    :maxdepth: 1
 
    devel/writing_custom_interfaces
-   devel/gitwash/index
 
 .. include:: links_names.txt
 
-Useful links for beginners
-===========================
-
-Getting started with Python - Tutorials. `Available here`__
-
-Python for Beginners `Available here`__
-
-   __ http://www.codecademy.com/en/tracks/python
-   __ https://www.python.org/about/gettingstarted/

doc/users/index.rst

@@ -11,15 +11,12 @@
    :maxdepth: 2
 
    install
-   vagrant
 
-   interface_tutorial
    caching_tutorial
 
 .. toctree::
    :maxdepth: 1
 
-   pipeline_tutorial
    plugins
    config_file
    debug

doc/users/install.rst

@@ -9,18 +9,17 @@ This page covers the necessary steps to install Nipype.
 Nipype for users
 ----------------
 
-Using conda
-~~~~~~~~~~~
-
-Installing nipype from the conda-forge channel can be achieved by adding conda-forge to your channels with::
-
-  conda config --add channels conda-forge
+Using docker
+~~~~~~~~~~~~
 
+You can follow the `Nipype tutorial <https://miykael.github.io/nipype_tutorial/>`_
 
-Once the conda-forge channel has been enabled, nipype can be installed with::
+Using conda
+~~~~~~~~~~~
 
-  conda install nipype
+Installing nipype from the conda-forge channel can be achieved by::
 
+  conda install --channel conda-forge nipype
 
 It is possible to list all of the versions of nipype available on your platform with::
 
@@ -36,18 +35,22 @@ The installation process is similar to other Python packages.
 
 If you already have a Python environment set up, you can do::
 
-  easy_install nipype
-
-or::
-
   pip install nipype
 
-
 If you want to install all the optional features of ``nipype``,
-use the following command (only for ``nipype>=0.13``)::
+use the following command::
 
   pip install nipype[all]
 
+Available options are::
+
+    'doc': ['Sphinx>=1.4', 'matplotlib', 'pydotplus'],
+    'tests': TESTS_REQUIRES,
+    'nipy': ['nitime', 'nilearn', 'dipy', 'nipy', 'matplotlib'],
+    'profiler': ['psutil'],
+    'duecredit': ['duecredit'],
+    'xvfbwrapper': ['xvfbwrapper'],
+
 
 Debian and Ubuntu
 ~~~~~~~~~~~~~~~~~
@@ -59,11 +62,14 @@ manager.
 Mac OS X
 ~~~~~~~~
 
-The easiest way to get nipype running on Mac OS X is to install Anaconda_ or
-Canopy_ and then add nipype by executing::
+The easiest way to get nipype running on Mac OS X is to install Miniconda_ and
+follow the instructions above. If you have a non-conda environment you can
+install nipype by typing::
 
-  easy_install nipype
+  pip install nipype
 
+Note that the above procedure may require availability of gcc on your system
+path to compile the traits package.
 
 From source
 ~~~~~~~~~~~
@@ -79,47 +85,42 @@ If you downloaded the source distribution named something
 like ``nipype-x.y.tar.gz``, then unpack the tarball, change into the
 ``nipype-x.y`` directory and install nipype using::
 
-    python setup.py install
+    pip install .
 
 **Note:** Depending on permissions you may need to use ``sudo``.
 
 
 Testing the install
 -------------------
 
-The best way to test the install is checking nipype's version ::
+The best way to test the install is checking nipype's version and then running
+the tests::
 
     python -c "import nipype; print(nipype.__version__)"
-
+    python -c "import nipype; nipype.test()"
 
 Installation for developers
 ---------------------------
 
 Developers should start `here <../devel/testing_nipype.html>`_.
 
-
 Recommended Software
-------------
+--------------------
 
 Strong Recommendations
 ~~~~~~~~~~~~~~~~~~~~~~
 
-IPython_ 0.10.2 - 1.0.0
-  Interactive python environment. This is necessary for some parallel
-  components of the pipeline engine.
+IPython_
+  Interactive python environment.
 
-Matplotlib_ 1.0 - 1.2
+Matplotlib_
   Plotting library
 
-`RDFLib <http://rdflib.readthedocs.org/en/latest/>`_ 4.1
-  RDFLibrary required for provenance export as RDF
-
 Sphinx_ 1.1
   Required for building the documentation
 
 `Graphviz <http://www.graphviz.org/>`_
-  Required for building the documentation. The python wrapper package (``graphviz``)
-  and the program itself both need to be installed.
+  Required for building the documentation.
 
 Interface Dependencies
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -148,7 +149,7 @@ Slicer_
   3.6 or later
 
 Nipy_
-  0.1.2+20110404 or later
+  0.4 or later
 
 Nitime_
   (optional)

doc/users/resource_sched_profiler.rst

@@ -1,8 +1,8 @@
 .. _resource_sched_profiler:
 
-============================================
+=============================================
 Resource Scheduling and Profiling with Nipype
-============================================
+=============================================
 The latest version of Nipype supports system resource scheduling and profiling.
 These features allows users to ensure high throughput of their data processing
 while also controlling the amount of computing resources a given workflow will

tools/interfacedocgen.py

@@ -440,6 +440,30 @@ def write_modules_api(self, modules, outdir):
             if not api_str:
                 continue
             # write out to file
+            mvalues = m.split('.')
+            if len(mvalues) > 3:
+                index_prefix = '.'.join(mvalues[1:3])
+                index_dir = os.path.join(outdir,
+                                         index_prefix)
+                index_file = index_dir + self.rst_extension
+                if not os.path.exists(index_dir):
+                    os.makedirs(index_dir)
+                    header = """.. AUTO-GENERATED FILE -- DO NOT EDIT!
+
+{name}
+{underline}
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   {name}/*
+                    """.format(name=index_prefix,
+                               underline='='*len(index_prefix))
+                    with open(index_file, 'wt') as fp:
+                        fp.write(header)
+                m = os.path.join(index_prefix,
+                                 '.'.join(mvalues[3:]))
             outfile = os.path.join(outdir,
                                    m + self.rst_extension)
             fileobj = open(outfile, 'wt')