Pandocs is required for rendering jupyter notebooks in the documentation

[drewoldag]

Pandoc, a package that is not installable via pip, is required to render the jupyter notebooks in the readthedocs documentation.

There's not an easy way to get give Pandoc to the user (we would have to direct them to install it themselves, and it might be difficult to explain concisely why or how). However, it is fairly easy to have it included in the readthedocs build, and it renders notebooks in the external documentation just fine.

However, because one of the pre-commit hooks is to build the documentation, it will fail unless:

1. Pandocs was installed successfully somehow - which would be great
2. We disable rendering the notebooks locally - this isn't exactly ideal.
3. We find a different tool that can accomplish this job - 😬

This is somewhat related to issue #109 . Since, even after organizing the dependencies, we'll still to figure out how to get Pandocs to the user in a seamless way.

[drewoldag]

Also related to #34

[drewoldag]

I was reading this SO article that mentions the use of source/_static to stash raw HTML files.

@olivialynn Have you by any chance tried rendering a notebook to HTML with nbconvert and then stashing the output in _static to see if it displays nicely in the docs? If it does, then perhaps this is an approach that can avoid requiring the user to install pandoc on their own.

[olivialynn]

I haven't, but I would have some hesitations going that way—I'm still on the fence about building out the notebooks at all within a precommit hook.

For our little demo notebook, this is no problem. However, if we envision actual users to do meaningful work with this, we will have to account for people who have notebooks that take 10 minutes, or 30, or even longer to run. Additionally, they might be notebooks that are really only meant to run on a better machine, not whatever laptop the scientist or developer might be using at the time.

Making someone figure out how to install pandoc based on what environment is annoying, sure. I bring this up not (just) to fix that frustration, but because making a user wait through the execution time of their notebook just to git commit -m "minor typo" seems like a pretty bad move to me.

If we wanted, we could make this a conditional option in the template, but I'm really worried about unnecessary clutter at that point. I'm glad we've put a lot of thought into this, but I'm of the opinion that that strategy I'd been implementing Monday (where we just remove notebook running from the precommit hook entirely) is the option that keeps the user's best interest in mind.

[olivialynn]

And as far as your nbconvert suggestion displaying in the docs goes—we can already see the html output of nbsphinx. Are you asking if we can embed it or link to it within the docs?

If we want to make the users host the output html in their repo, we can, but I'm not sure what we gain by making them navigate to separate "just the notebook page" (if I am properly picturing what's described in the SO post) that loses the sidebar navigation or any other concept of RTD. I mentioned Monday that I've already included pandoc installation into the GitHub workflow (and as we've seen, it's never been a problem on RTD), so I don't know what that strategy would fix.

[drewoldag]

All of the concerns here were addressed in PR #125.