Merge pull request #1896 from oesteban/enh/SphinxExtension-workflows

[ENH] Sphinx extension to plot workflows

Author: satra

CHANGES

@@ -1,6 +1,7 @@
 Upcoming Release
 =====================
 
+* ENH: Sphinx extension to plot workflows (https://github.com/nipy/nipype/pull/1896)
 * ENH: Added non-steady state detector for EPI data (https://github.com/nipy/nipype/pull/1839)
 * ENH: Enable new BBRegister init options for FSv6+ (https://github.com/nipy/nipype/pull/1811)
 * REF: Splits nipype.interfaces.utility into base, csv, and wrappers (https://github.com/nipy/nipype/pull/1828)
@@ -22,7 +23,7 @@ Upcoming Release
 
 0.13.0-rc1 (January 4, 2017)
 ===============================
- 
+
 * FIX: Compatibility with traits 4.6 (https://github.com/nipy/nipype/pull/1770)
 * FIX: Multiproc deadlock (https://github.com/nipy/nipype/pull/1756)
 * TST: Replace nose and unittest with pytest (https://github.com/nipy/nipype/pull/1722, https://github.com/nipy/nipype/pull/1751)

doc/conf.py

@@ -42,16 +42,16 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.todo',
-              'sphinx.ext.pngmath',
+              'sphinx.ext.imgmath',
               'sphinx.ext.inheritance_diagram',
               'sphinx.ext.graphviz',
               'sphinx.ext.autodoc',
               'sphinx.ext.doctest',
-              'sphinx.ext.pngmath',
               'sphinx.ext.autosummary',
               'numpy_ext.numpydoc',
               'matplotlib.sphinxext.plot_directive',
               'matplotlib.sphinxext.only_directives',
+              'nipype.sphinxext.plot_workflow',
               #'IPython.sphinxext.ipython_directive',
               #'IPython.sphinxext.ipython_console_highlighting'
               ]

doc/documentation.rst

@@ -24,10 +24,12 @@ Previous versions:  `0.12.0 <http://nipype.readthedocs.io/en/0.12.0/>`_ `0.11.0
             :maxdepth: 2
 
             users/index
+            
          .. toctree::
             :maxdepth: 1
 
             changes
+
        * Developer
 
          .. toctree::

doc/users/index.rst

@@ -39,6 +39,8 @@
    mipav
    nipypecmd
    aws
+   resource_sched_profiler
+   sphinx_ext
 
 
 

doc/users/sphinx_ext.rst

@@ -0,0 +1,14 @@
+
+.. _sphinx_ext:
+
+Sphinx extensions
+-----------------
+
+
+To help users document their *Nipype*-based code, the software is shipped
+with a set of extensions (currently only one) to customize the appearance
+and simplify the generation process.
+
+.. automodule:: nipype.sphinxext.plot_workflow
+    :undoc-members:
+    :noindex:

nipype/info.py

@@ -152,7 +152,7 @@ def get_nipype_gitversion():
 ]
 
 EXTRA_REQUIRES = {
-    'doc': ['Sphinx>=0.3', 'matplotlib', 'pydotplus'],
+    'doc': ['Sphinx>=1.4', 'matplotlib', 'pydotplus'],
     'tests': TESTS_REQUIRES,
     'fmri': ['nitime', 'nilearn', 'dipy', 'nipy', 'matplotlib'],
     'profiler': ['psutil'],

nipype/pipeline/engine/utils.py

@@ -1018,20 +1018,18 @@ def export_graph(graph_in, base_dir=None, show=False, use_execgraph=False,
                                suffix='_detailed.dot',
                                use_ext=False,
                                newpath=base_dir)
-    logger.info('Creating detailed dot file: %s' % outfname)
     _write_detailed_dot(graph, outfname)
     cmd = 'dot -T%s -O %s' % (format, outfname)
     res = CommandLine(cmd, terminal_output='allatonce').run()
     if res.runtime.returncode:
         logger.warn('dot2png: %s', res.runtime.stderr)
     pklgraph = _create_dot_graph(graph, show_connectinfo, simple_form)
-    outfname = fname_presuffix(dotfilename,
-                               suffix='.dot',
-                               use_ext=False,
-                               newpath=base_dir)
-    nx.drawing.nx_pydot.write_dot(pklgraph, outfname)
-    logger.info('Creating dot file: %s' % outfname)
-    cmd = 'dot -T%s -O %s' % (format, outfname)
+    simplefname = fname_presuffix(dotfilename,
+                                  suffix='.dot',
+                                  use_ext=False,
+                                  newpath=base_dir)
+    nx.drawing.nx_pydot.write_dot(pklgraph, simplefname)
+    cmd = 'dot -T%s -O %s' % (format, simplefname)
     res = CommandLine(cmd, terminal_output='allatonce').run()
     if res.runtime.returncode:
         logger.warn('dot2png: %s', res.runtime.stderr)
@@ -1041,6 +1039,10 @@ def export_graph(graph_in, base_dir=None, show=False, use_execgraph=False,
         if show_connectinfo:
             nx.draw_networkx_edge_labels(pklgraph, pos)
 
+    if format != 'dot':
+        outfname += '.%s' % format
+    return outfname
+
 
 def format_dot(dotfilename, format=None):
     """Dump a directed graph (Linux only; install via `brew` on OSX)"""
@@ -1052,8 +1054,10 @@ def format_dot(dotfilename, format=None):
             raise IOError("Cannot draw directed graph; executable 'dot' is unavailable")
         else:
             raise ioe
-    else:
-        logger.info('Converting dotfile: %s to %s format' % (dotfilename, format))
+
+    if format != 'dot':
+        dotfilename += '.%s' % format
+    return dotfilename
 
 
 def make_output_dir(outdir):

nipype/pipeline/engine/workflows.py

@@ -429,15 +429,19 @@ def write_graph(self, dotfilename='graph.dot', graph2use='hierarchical',
             self.write_hierarchical_dotfile(dotfilename=dotfilename,
                                             colored=graph2use == "colored",
                                             simple_form=simple_form)
-            format_dot(dotfilename, format=format)
+            outfname = format_dot(dotfilename, format=format)
         else:
             graph = self._graph
             if graph2use in ['flat', 'exec']:
                 graph = self._create_flat_graph()
             if graph2use == 'exec':
                 graph = generate_expanded_graph(deepcopy(graph))
-            export_graph(graph, base_dir, dotfilename=dotfilename,
-                         format=format, simple_form=simple_form)
+            outfname = export_graph(graph, base_dir, dotfilename=dotfilename,
+                                    format=format, simple_form=simple_form)
+
+        logger.info('Generated workflow graph: %s (graph2use=%s, simple_form=%s).' % (
+            outfname, graph2use, simple_form))
+        return outfname
 
     def write_hierarchical_dotfile(self, dotfilename=None, colored=False,
                                    simple_form=True):

nipype/sphinxext/__init__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+from __future__ import print_function, division, absolute_import, unicode_literals