Repository: sphinx-gallery/sphinx-gallery

Issue:
RST directives remain in ipynb
The IPython ipynb downloads don't strip all irrelevant stuff e.g. links:

http://martinos.org/mne/dev/_downloads/plot_background_filtering.ipynb

Looks like this:

![screenshot from 2016-08-30 10-01-29](https://cloud.githubusercontent.com/assets/2365790/18092077/e9e5ebf0-6e98-11e6-9d29-781e6f6461d3.png)


Should we remove lines starting with `.. `?

Discussion:
GaelVaroquaux: Beautiful!

There are now conflicts, and I suspect that it's due to #139 being merged. Maybe this PR could actually be refactored to weave in well with the code introduced in #139.
Titan-C: It looks great, thank you.

I recently merged a fix for the rendered math too, which covers some extra cases too. You'll have to rebase.

Finally, would it be possible to have the content of the test also displayed in the gallery? the one on the tutorials folder that covers more the notebook styled examples.  That way we can make people aware that we support this.
lesteve: I am a bit worried about the maintainability of ReST to markdown conversion via regexps going forward. I don't know whether there is a cleaner alternative. I think it's fine as long as we don't build high expectations about the markdown support in the notebook.

GaelVaroquaux: > I am a bit worried about the maintainability of ReST to markdown
> conversion via regexps going forward. I don't know whether there is a
> cleaner alternative. I think it's fine as long as we don't build high
> expectations about the markdown support in the notebook.

For now, I think that we should do this. In the longer term, maybe we
should use docutils.examples.internals: the first argument is a document
tree that we can walk (eg with the "traverse" method).

lesteve: FWIW I found out that there is some markdown support in sphinx. Maybe using markdown in the examples would make sense since we generally do not use advanced ReST functionalities. That was just a thought and talking about the long term here obviously.

Quoting from https://github.com/sphinx-doc/sphinx/issues/825#issuecomment-180197293:

> Actually, sphinx can build Markdown document by using:

> pip install commonmark recommonmark

> conf.py

> ```
source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
```

> It's still limited, but usable.

Eric89GXL: > I recently merged a fix for the rendered math too, which covers some extra cases too. You'll have to rebase.

Yeah that must be the conflict, rebase should be straightforward (I hope!).

> Maybe using markdown in the examples would make sense since we generally do not use advanced ReST functionalities. 

Maybe, but now in MNE-Python we have a lot of tutorials in ReST syntax, so changing them would be :( But maybe going forward it would make sense if someone wants to try it out and make nice examples.

Patch:
diff --git a/.gitignore b/.gitignore
index c9e4050..f28edf3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,6 +39,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+*.orig
 
 # Translations
 *.mo
@@ -50,6 +51,7 @@ coverage.xml
 # Sphinx documentation
 doc/_build/
 doc/auto_examples
+doc/auto_mayavi_examples
 doc/tutorials/
 doc/modules/generated
 
diff --git a/setup.py b/setup.py
index eca3363..31d9a71 100644
--- a/setup.py
+++ b/setup.py
@@ -6,21 +6,12 @@ Installer Sphinx extension for gallery generator
 """
 
 import codecs
-import os
 from setuptools import setup, find_packages
 import sphinx_gallery
 
 with codecs.open('README.rst', mode='r', encoding='utf-8') as f:
     long_description = f.read()
 
-# XXX : don't force requirements in setup.py as it tends to break
-#       people's setups
-install_requires = []
-
-if os.environ.get('READTHEDOCS', None) == 'True':
-    # So that we can build documentation using seaborn
-    install_requires = ['seaborn']
-
 
 setup(
     name="sphinx-gallery",
@@ -34,7 +25,9 @@ setup(
     url="https://github.com/sphinx-gallery/sphinx-gallery",
     author="Óscar Nájera",
     author_email='najera.oscar@gmail.com',
-    install_requires=install_requires,
+    # XXX : don't force requirements in setup.py as it tends to break people
+    # install_requires= ['Sphinx', 'matplotlib', 'pillow'],
+    install_requires=[],
     setup_requires=['nose>=1.0'],
     license='3-clause BSD',
     classifiers=['Intended Audience :: Developers',
diff --git a/sphinx_gallery/notebook.py b/sphinx_gallery/notebook.py
index b05b9ff..fc0fccf 100644
--- a/sphinx_gallery/notebook.py
+++ b/sphinx_gallery/notebook.py
@@ -11,11 +11,13 @@ Class that holds the Jupyter notebook information
 # License: 3-clause BSD
 
 from __future__ import division, absolute_import, print_function
+from functools import partial
 import json
 import os
 import re
 import sys
 
+
 def ipy_notebook_skeleton():
     """Returns a dictionary with the elements of a Jupyter notebook"""
     py_version = sys.version_info
@@ -46,6 +48,14 @@ def ipy_notebook_skeleton():
     return notebook_skeleton
 
 
+def directive_fun(match, directive):
+    """Helper to fill in directives"""
+    directive_to_alert = dict(note="info", warning="danger")
+    return ('<div class="alert alert-{0}"><h4>{1}</h4><p>{2}</p></div>'
+            .format(directive_to_alert[directive], directive.capitalize(),
+                    match.group(1).strip()))
+
+
 def rst2md(text):
     """Converts the RST text from the examples docstrigs and comments
     into markdown text for the Jupyter notebooks"""
@@ -61,6 +71,30 @@ def rst2md(text):
     inline_math = re.compile(r':math:`(.+?)`', re.DOTALL)
     text = re.sub(inline_math, r'$\1$', text)
 
+    directives = ('warning', 'note')
+    for directive in directives:
+        directive_re = re.compile(r'^\.\. %s::((?:.+)?(?:\n+^  .+)*)'
+                                  % directive, flags=re.M)
+        text = re.sub(directive_re,
+                      partial(directive_fun, directive=directive), text)
+
+    links = re.compile(r'^ *\.\. _.*:.*$\n', flags=re.M)
+    text = re.sub(links, '', text)
+
+    refs = re.compile(r':ref:`')
+    text = re.sub(refs, '`', text)
+
+    contents = re.compile(r'^\s*\.\. contents::.*$(\n +:\S+: *$)*\n',
+                          flags=re.M)
+    text = re.sub(contents, '', text)
+
+    images = re.compile(
+        r'^\.\. image::(.*$)(?:\n *:alt:(.*$)\n)?(?: +:\S+:.*$\n)*',
+        flags=re.M)
+    text = re.sub(
+        images, lambda match: '![{1}]({0})\n'.format(
+            match.group(1).strip(), (match.group(2) or '').strip()), text)
+
     return text
 
 
diff --git a/tutorials/plot_notebook.py b/tutorials/plot_notebook.py
index 558f7d4..5809cd5 100644
--- a/tutorials/plot_notebook.py
+++ b/tutorials/plot_notebook.py
@@ -99,3 +99,16 @@ print('Some output from Python')
 # code directly will see the plots; this is not necessary for creating the docs
 
 plt.show()
+
+############################################################################
+# You can also include :math:`math` inline, or as separate equations:
+#
+# .. math::
+#
+#    \exp(j\pi) = -1
+#
+# You can also insert images:
+#
+# .. image:: http://www.sphinx-doc.org/en/stable/_static/sphinxheader.png
+#    :alt: Sphinx header
+#


Test patch:
diff --git a/sphinx_gallery/tests/test_notebook.py b/sphinx_gallery/tests/test_notebook.py
index a76ec1f..93a240a 100644
--- a/sphinx_gallery/tests/test_notebook.py
+++ b/sphinx_gallery/tests/test_notebook.py
@@ -26,3 +26,43 @@ def test_latex_conversion():
 \begin{align}\mathcal{H} &= 0 \\
    \mathcal{G} &= D\end{align}"""
     assert_equal(align_eq_jmd, rst2md(align_eq))
+
+
+def test_convert():
+    """Test ReST conversion"""
+    rst = """hello
+
+.. contents::
+    :local:
+
+This is :math:`some` math :math:`stuff`.
+
+.. note::
+    Interpolation is a linear operation that can be performed also on
+    Raw and Epochs objects.
+
+.. warning::
+    Go away
+
+For more details on interpolation see the page :ref:`channel_interpolation`.
+.. _foo: bar
+
+.. image:: foobar
+  :alt: me
+  :whatever: you
+"""
+
+    markdown = """hello
+
+This is $some$ math $stuff$.
+
+<div class="alert alert-info"><h4>Note</h4><p>Interpolation is a linear operation that can be performed also on
+    Raw and Epochs objects.</p></div>
+
+<div class="alert alert-danger"><h4>Warning</h4><p>Go away</p></div>
+
+For more details on interpolation see the page `channel_interpolation`.
+
+![me](foobar)
+"""  # noqa
+    assert_equal(rst2md(rst), markdown)