Drop examples from main repository

[effigies]

Summary

I've moved the examples/ directory into niflows/nipype1-examples, and set up CircleCI testing on these.

As we further develop niflows infrastructure, we should make sure that a release branch (or pre-release on PyPI) triggers tests with the new nipype on all niflows. Once that is working, we can remove the examples/ directory and drop the extended tests from nipype.

[effigies]

I've pushed this off for quite a while, so apologies if this delays 1.5.0. We need to decide what will constitute completion of this issue. The examples are used for CI, documentation and are intended to be runnable by users.

1. CI - Do we test on each commit here, as before, or move to niflows? If the latter, how and how often is it triggered?
2. Docs - Should we build on niflows and set up intersphinx? Directly include? What are the mechanics for making sphinx play nicely with an external repository?
3. User friendliness - an informative README in examples/ explaining where things have gone and how to continue using them.

Inputs on 1 & 2 would be very much appreciated.

(cc @oesteban @satra @djarecka @mgxd)

[oesteban]

My 2ct

• CI - Do we test on each commit here, as before, or move to niflows? If the latter, how and how often is it triggered?

Running the full workflows on each commit is not giving us great coverage or helping us catch many bugs. First, because the examples only exercise a small set of all the available interfaces. Second, because we check on something we don't care much about (i.e., the particular examples we are testing are chosen for the intuition that will cover a good bunch of nipype code, but nothing more elaborate).

For a while I've been trying to think of some "test" plugin or modification of plugin for nipype that "fakes" any command line call (i.e., checks all inputs exist and creates empty files for every output). But for that, we would need to nail the automated prediction of outputs (along the lines of #3150), and very likely many other things.

• Docs - Should we build on niflows and set up intersphinx? Directly include? What are the mechanics for making sphinx play nicely with an external repository?

intersphinx just resolves object references, but will not render autodoc documentation or anything outside the project.

At this moment, examples are built separately in a step before sphinx-build is called. We can keep doing that but fetching the examples from niflows anyways.
Alternatively, outsourcing the examples completely does not seem like a horrible idea - most of the user's documentation has been moved to Mikael's notebooks which are hosted and built outside nipype. This would be pretty much the same thing.

• User friendliness - an informative README in examples/ explaining where things have gone and how to continue using them.

+1

[effigies]

I'm good with moving examples to a separate site and linking. In the short term, since it sounds easy, I'll plan on continuing to build into the nipype docs, but I've opened niflows/nipype1-examples#3.

[satra]

i'm fine with moving examples.