Please use "Fix #issueNumber" this way the associated issue gets closed automatically when the PR is merged. For more details, look at this.

I have edited your description but please remember to do it next time.

I think we would need tests for this and probably a new entry in the build matrix with pypandoc and pandoc installed. The latter can be installed through anaconda.

Also I am wondering what happens if you have pypandoc but not pandoc installed. Is there a clear error message?

If pypandoc is installed but not pandoc, OSError is raised.
That's why two errors are caught. We can be logging which implementation is used like this

try:
    import pypandoc
    print('Using pandoc for converting rst to md in notebooks')
except (ImportError, OSError) as e:
    print('Pandoc not found. Error: {}. Falling back to regex based parser'.format(e))

Please show me where I should add the above and tests.

I don't like having our rst2md code in the except block. I would rather write a new wrapper function like

def rst2md(args):
    try:
        import pypandoc
        return pypandoc.rst2md(args)
    except:
        return sphx_glr_rst2md(args)

Then we can document this function explaining the pypandoc use and the default option of a regexp based conversion in our library. Also our function documentation remains available.

I'm fine not throwing a message if pandoc is not installed, is an optional dependecy and just as we don't complain about mayavi or seaborn being installed here it shall not be the case. Optional dependencies remain user responsibility.

We do need to add this case to the test matrix this dependency. I don't like the anaconda install because it has to go trough conda-forge(but it is just another line in the .travis.yml, and travis time is for free so include it at will). I would do the install trough pip and then use pypandoc itself to download the official binary.

$ python -c "import pypandoc;pypandoc.download_pandoc()"

This command takes care of it. Finally we have to include this in the changes and put some documentation in the advanced_configuration.rst

I don't like the anaconda install because it has to go trough conda-forge

pandoc is accessible through conda without conda-forge. pypandoc is accessible through pip. This is what I would do for simplicity.

I don't like having our rst2md code in the except block.

Moved existing code to a new function as you suggested.

We do need to add this case to the test matrix this dependency.

Do I have to create a new environment here? or Use existing one?
I prefer using pip install pypandoc and
python -c "import pypandoc;pypandoc.download_pandoc()" . I need to these two lines to this block right?

I'm sorry but I'm a noob when it comes to travis.

For testing with travis and also I would like to see in the circle ci artifacts this output you need this

diff --git a/.travis.yml b/.travis.yml
index 438e17ec..ed79e259 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -32,6 +32,8 @@ matrix:
       env: DISTRIB="conda" PYTHON_VERSION="3.4"
     - os: linux
       env: DISTRIB="conda" PYTHON_VERSION="3.5"
+    - os: linux
+      env: DISTRIB="conda" PYTHON_VERSION="3.5" PYPANDOC="True"
 before_install:
     - if [ "$DISTRIB" == "conda" ]; then
          wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh;
@@ -51,6 +53,9 @@ install:
         if [ "$PYTHON_VERSION" == "2.7" ]; then
           conda install --yes mayavi;
         fi;
+        if [ "$PYPANDOC" == "True"]; then
+            python -c "import pypandoc;pypandoc.download_pandoc()";
+        fi;
       fi;
     - pip install -r requirements.txt
     - if [ "$DISTRIB" == "ubuntu 14" ]; then pip install seaborn sphinx==1.4.9; fi;
diff --git a/circle.yml b/circle.yml
index dc3a807f..b153aebd 100644
--- a/circle.yml
+++ b/circle.yml
@@ -16,6 +16,7 @@ dependencies:
     - sed -i "s/ENABLE_USER_SITE = .*/ENABLE_USER_SITE = False/g" /home/ubuntu/miniconda/envs/circleenv/lib/python2.7/site.py
     - conda install -n circleenv --yes numpy scipy seaborn mayavi setuptools matplotlib pillow sphinx nose sphinx_rtd_theme
     - pip install -r requirements.txt
+    - python -c "import pypandoc;pypandoc.download_pandoc()"
 
   override:
     - python setup.py develop

@Titan-C I think this is ready to be merged.

@chsasank Thank you so much for keeping up with this. The code looks great and I'm happy with the documentation. But just now with the Circle CI in place I checked the output of pypandoc and comparied it against what Sphinx-gallery supports.

I'm disappointed on the output of Pandoc as it misses conversions we already support, we certainly need more calibration for it beyond the default. Have a look at:

• https://46-25860190-gh.circle-artifacts.com/0/home/ubuntu/sphinx-gallery/rtd_html/auto_examples/plot_quantum.html#sphx-glr-auto-examples-plot-quantum-py
  It misses multiline Latex equations
• https://46-25860190-gh.circle-artifacts.com/0/home/ubuntu/sphinx-gallery/rtd_html/auto_examples/sin_func/plot_sin.html#sphx-glr-auto-examples-sin-func-plot-sin-py
  The See also box is removed instead of kept without unconverted
• https://46-25860190-gh.circle-artifacts.com/0/home/ubuntu/sphinx-gallery/rtd_html/tutorials/plot_parse.html#sphx-glr-tutorials-plot-parse-py
  Warning boxes are washed, code-block is removed,

We have test for the latex conversion. Travis being green and pandoc not having good latex conversion means travis was not setup correctly. (My error) The if clause needs to be

-        if [ "$PYPANDOC" == "True"]; then
+        if [ "$PYPANDOC" == "True" ]; then

The white-space is relevant

Updated. Build fails because

1. '$T<0$ and $U&gt;0$\n' is produced instead of '$T<0$ and $U&gt;0$'. New line is inserted. I don't think this is a issue. Test can be fixed with strip()
2. note and warning directives are not converted to divs as expected by the tests.

Sasank.

Yes build should fail on Pandoc because it is not converting everything as we would want. We expect warning blocks and multiline Latex to work. (The inline Latex, first fail is indeed no big deal)

Hey @Titan-C @lesteve,

Is there anything I should do before closing/merging this PR?

note and warning directives are not converted to divs as expected by the tests.

Is this the feature you want but pandoc doesn't support?

Arguably, that's just two tags that are not supported by pandoc. Output is not unreasonable either:

note

Interpolation is a linear operation that can be performed also on

Compare this to current rst2md parser which misses so many tags (see rst and output)

Anyway, closing the PR

So, is there no way to present titles, or h3 and h4 headers in .ipynb that are converted from .py files? Seems like a big limitation.

Rather than commenting in a closed PR, please open an issue with more details and ideally a way to reproduce what you are seeing.