mention pandoc dependency in the documentation

[brechtm]

The README.rst nor the docs on ReadTheDocs mention pandoc as a dependency.

[mgeier]

You're right, I completely missed that.

Would you mind creating a PR for that?

Here are the instructions of nbconvert:
https://nbconvert.readthedocs.io/en/latest/install.html#installing-pandoc

Strangely, they don't mention the conda channel conda-forge, which has a package pandoc.

Just for the record, once #36 is implemented, the pandoc dependency will most likely be replaced by something else.

[TomAugspurger]

Related to this, would you be open to an option allowing a doc build to continue, even if pandoc is not installed? We'd like to use nbsphinx as part of the pandas doc build, but don't want to require our contributors to install pandoc.

I don't know if it should follow the nbsphinx_allow_errors option or not.

[mgeier]

@TomAugspurger The pandoc dependency will vanish as soon as #36 is done, which I guess will not be soon at all.

Until that, pandoc is used to convert every single Markdown cell, so I don't really see how this could be made optional.

What do you suggest should happen if pandoc is not available?
Just skipping the Markdown cells wouldn't make sense, right?

[TomAugspurger]

Hmm #36 does seem tricky...

What do you suggest should happen if pandoc is not available?
Just skipping the Markdown cells wouldn't make sense, right?

Right, I would think the entire notebook is skipped as soon as you hit a nbconvert.utils.pandoc.PandocMissing.

For some more background, in pandas we currently have a single notebook as part of the doc build. That failing to build isn't the end of the world for a contributor just updating some other section of the docs. We can work around this as part of our build process if you think our use-case is too niche.

[mgeier]

OK, I see your use case now.

What about turning the PandocMissing exception into a warning?

This would be quite simple, but how to tell Sphinx to discard the current source file and continue with the next?

While playing around with this, I found out that a change in nbconvert release 5.0 (see jupyter/nbconvert#436) disabled my function markdown2rst()!
I've tried to fix this in #101, can you please try if this works for you?

[mgeier]

@TomAugspurger I've asked in the Sphinx mailing list, got two work-arounds and came up with a third one, see https://groups.google.com/forum/#!topic/sphinx-users/lEJbtgv_uzk.

I think I could disable notebooks when pandoc isn't found, the question is what should be done instead?

Should the resulting output pages just be empty (which means that they would also not appear in any table of contents because they don't have a title) or should they be replaced with some error page?

If latter, what should be displayed in a TOC instead of the title of the notebook?

[TomAugspurger]

@mgeier thanks.

FWIW, I was able to work around this in pandas pretty easily here. I just check to see if nbconvert can find a pandoc. In this case, we skip the notebook entirely, so it's skipped in the TOC (which is OK for us). It's probably easier for pandas to do it outside of the actual build processes, than for nbsphinx to abort in the middle of converting a notebook.

I don't know what the desired behavior would be if we added something in nbsphinx. If these were behind a config setting, then I think a blank page or no page at all is OK, as long as it raises an exception by default.

[mgeier]

I've added #102 to deal with the original issue. Is it OK?

@TomAugspurger If you need something changed in nbsphinx, just let me know!
I'm looking forward to many pandas notebooks converted with nbsphinx!

[TomAugspurger]

#102 looks good!

I'm looking forward to it too :)