Looks good! The one catch is that we'll need to add something in the documentation about installing pandoc if users wish to build the notebooks locally with sphinx (as pandoc is a haskell library, so we can't bundle it into pip requirements)
Without pandoc in my rail conda environment, running make html from the docs/ directory of this PR results in an interrupted run and:
Notebook error:
PandocMissing in examples/core_examples/FileIO_DataStore.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
Running conda install pandoc allows make html to run as expected.
Proposed solutions include:
explaining this in the documentation, in a section relevant to devs trying to build notebooks (or documentation in general) locally
we could also include a comment in our Makefile, in the hopes that anyone encountering trouble with make commands will read that
we could include pandoc in our other conda packages in the standard rail install instructions, but I hesitate to add that kind of overhead for such a relatively niche use case
(This should not be an issue on ReadTheDocs, as pandoc should be automatically included. If I recall, there is a toggle in Advanced Settings where you can remove this, but unless we run into issues we can assume we don't have that set.)
Looks good! The one catch is that we'll need to add something in the documentation about installing pandoc if users wish to build the notebooks locally with sphinx (as pandoc is a haskell library, so we can't bundle it into pip requirements)
Without pandoc in my rail conda environment, running
make html
from the docs/ directory of this PR results in an interrupted run and:Running
conda install pandoc
allowsmake html
to run as expected. Proposed solutions include:make
commands will read that(This should not be an issue on ReadTheDocs, as pandoc should be automatically included. If I recall, there is a toggle in Advanced Settings where you can remove this, but unless we run into issues we can assume we don't have that set.)