Auto notebooks from examples with shpinx-gallery

[rflamary]

This PR handle automatic conversion from examples to notebooks with sphinx-gallery (cf issue #16 ). It does not change the code of the features but aim at making this conversion smooth while keeping the readthedoc documentation running.

Main changes:

• Now notebooks (in the notebooks folder) are automatically generated from examples (in the examples folder) when the doc is built.
• All examples have a syntax that is compatible with both proper sphinx-gallery output and notebooks with proper subsections/titles.

This was a very bumpy road for several reasons:

• It is still difficult to have a doc that build smoothly in local and readthedoc. The only solution I found is to build the doc locally with sphinx-gallery enabled, which creates the *rst and so on and remove the sphinx-gallery extension for readthedoc compatibility. We cannot build the whole doc on readthedoc since POT require compilation which is forbidden. The local build is performed but the script nb_build in the docs folder (it temporarily removes the mock modules necessary for building the docs without compilation).

• Sphinx-gallery does not do a proper rst to md conversion fro the notebooks (see their issue 219). Which means that in order to have proper sub-title we need to put in the code something like

##############################################################################
# Subtitle
# --------

Because this code is the only one that allows for both titles in rst and mardown and renders well in the notebooks and documentation.

• To the best of my knowledge sphinx gallery do not compile the notebooks so they are empty shells with no images or output. This is why I added a little script to automatically run and store in the notebooks folder all notebooks files that have been changed after documentation generation. this is done automatically when building the local doc. The notebook running itself is performed by ```nb_run_conv`` that obviously requires to have jupyter installed.

[agramfort]

@rflamary you should not put the rendered notebook in the main source tree. It will make its size explode.

one option would be to build the doc eg with circleci like sklearn does it and it gets pushed to the website repo that is hosted on github pages.