search

OpenSenseAction / poligrain

Simplify common tasks for working with point, line and gridded sensor data, focusing on rainfall observations.
https://poligrain.readthedocs.io
BSD 3-Clause "New" or "Revised" License
2 stars 10 forks source link

Pandoc package requires explicit installation #30

Closed nblettner closed 3 months ago

nblettner commented 3 months ago

I encountered an issue when getting started to contribute. Following the workflow for contributing an error was raised when executing nox -s docs -- --serve (same for nox -s docs).  Part of the error message was:

nbconvert.utils.pandoc.PandocMissing: Pandoc wasn't found.

That is, pandoc is not installed automatically based on the current setup. Instead, pandoc needs to be installed separately, and this installation is essentially only possible via conda (see pandoc project description). It might not be important in which environment it is installed, and the issue may go unnoticed if you happen to have had it installed before. Also, when executed online, no error is raised, presumably  because pandoc is part of the image that is used for the container in which the code runs for the build of the docs on readthedocs.org.

For developing, it seems like the use of conda and an explicit installation of pandoc is required. The workflow for contributing needs to be adjusted accordingly.

cchwala commented 3 months ago

Thanks for finding and raising this issue @nblettner.

I just found that there is a pypandoc version called pypandoc_binary which installs also the pandoc binaries via pip, see the info here.

Hence, one easy fix right now, without requiring everyone to use a conda env as basis, could be to add pypandoc_binary as dependency for the doc build process.

cchwala commented 3 months ago

After uninstalling pandoc from my conda base env I can reproduce this error.

cchwala commented 3 months ago

The good news is that pip install pypandoc_binary results in having a pandoc binary in the env it is installed to. The bad news is that the pandoc binary is not added to the PATH or to the /bin directory of the env.

Making the env aware of the pandoc binary is complicated since we have to do that inside the nox session that runs the build of the docs.

My current solution is to use a small script that creates a symbolic link form the env's /bin dir to the pandoc binary that lives somwhere in e.g. ......./lib/python3.10/site-packages/pypandoc/files/pandoc.