由于缺少 pandoc，构建文档失败

Question

问题

单击 readthedocs.io Web 界面上的“构建”时，我无法成功构建文档，但它在我的本地计算机上构建得很好。为了测试这是一个环境问题，我创建了一个虚拟环境：

conda create virtualenv -n venv
conda env export -n venv
source activate venv

然后我将 requirements.txt 文件安装为：

pip install -r requirements.txt

然后跑了

make clean html

在虚拟环境和在线 buildthedocs 中，我收到错误：

Notebook error:
PandocMissing in ex_degassing.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
http://pandoc.org/installing.html
make: *** [html] Error 2

我已经搜索并搜索了一个解决方案，但我最好的猜测是 pandoc 不是通过 pip 安装的，即使它在 requirements.txt 文件中。我还尝试通过在我的 requirements.txt 文件中将 pandoc 替换为 git+git://github.com/jgm/pandoc#egg=pandoc 来告诉它从源代码构建，但这不起作用（请参阅下文了解我的文件的外观）。我可以在本地机器上轻松安装 pandoc，但无法通过我的虚拟环境中的 requirements.txt 文件或 readthedocs 安装。

我的一些文件

这是我的 requirements.txt 文件：

sphinx>=1.4
sphinx_rtd_theme
ipykernel
nbsphinx
pandas
pandoc
numpy
matplotlib
ipynb
scipy

我通读了所有 readthedocs documentation，具有讽刺意味的是，我发现构建文档对于我有限的编码能力的人来说严重不足。我尝试制作 readthedocs.yml 和 environment.yaml 文件，但我不知道它们是否在做任何事情或者是否正确编写。为了完整起见，以下是这些文件：

readthedocs.yml

# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/conf.py
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt

environment.yaml

channels:
  - conda-forge
dependencies:
  - python =3.7
  - pandoc

总结

我已经使用 readthedocs 和 sphinx 创建了精美的文档，但我无法将它构建在网络上。我该如何：a）解决安装 pandoc 的问题（这是问题吗？？）或 b）消除对 pandoc 的需要（例如，有没有办法在我的文档中包含 jupyter notebook 文件而不需要 pandoc？如何这样做？）？

非常感谢任何人的建议！

Answer 1

我遇到了同样的问题。

Notebook error:
PandocMissing in getting_started.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html

似乎是通过pip 安装pandoc 还是使用conda 安装有区别。

尝试以下方法：

pip uninstall pandoc
conda install pandoc

使用conda 版本解决了我机器上的问题。

另一方面，如果您使用poetry，您也可能会遇到相同的错误消息，即PandocMissing。在我的机器上，通过其 Windows 安装程序安装 Pandoc 也解决了这个问题：https://pandoc.org/installing.html。

Answer 2

目前PyPI page for pandocs 上没有很好地解释它，但 pandoc 实际上是用 Haskell 编写的，而不是 Python。您可以使用pip install pandoc 安装的 python 的 pandoc 包不附带 pandoc 的可执行副本，它只是一个包装器，用于在 python 中提供与 pandoc 的绑定。它通过对您的 pandoc 的系统副本进行 shell 调用来实现这一点，因此您需要将 install a copy of the actual pandoc executable 单独发送到您的系统，以便 python 绑定可以绑定一些东西！

例如，在 Debian/Ubuntu 上，除了使用 pip 安装 python 绑定之外，您还需要使用 apt 安装 pandoc 的系统副本。

sudo apt install pandoc
pip install pandoc

虽然您可以在本地系统上执行此操作，但这并不是让它在 readthedocs 上工作的可行解决方案。

---

与此相反，conda 试图使软件包工作，而不管系统其余部分上安装了什么。因此 conda pandoc 包附带了 pandoc 的实际副本，它使用它而不是尝试使用 pandoc 的系统副本。如果您使用的是 conda，只需运行一个命令即可让 pandoc 在 python 中工作：

conda install pandoc

如果您为 readthedocs 规范使用 conda 环境（就像 OP 的情况一样），您只需将 pandoc 添加到 conda 部分而不是 env 的 pip 部分。

---

您可以使用 pip 安装的 pandoc package on PyPI 实际上并不是 python 的官方 pandoc 包。还有pypandoc和py-pandoc，同样是非官方的。

据说py-pandoc是通过python接口安装pandoc的一站式商店。我认为您只需执行pip install py-pandoc 或conda install pandoc 即可立即生效，但由于缺乏文档我不确定。

就我自己而言，我正在使用 Sphinx 来构建文档。我个人对构建 python 文档（包括在 readthedocs 上）时安装 pandoc 问题的解决方案是将以下代码块添加到 conf.py。

def ensure_pandoc_installed(_):
    import pypandoc

    # Download pandoc if necessary. If pandoc is already installed and on
    # the PATH, the installed version will be used. Otherwise, we will
    # download a copy of pandoc into docs/bin/ and add that to our PATH.
    pandoc_dir = os.path.join(DOCS_DIRECTORY, "bin")
    # Add
    if pandoc_dir not in os.environ["PATH"].split(os.pathsep):
        os.environ["PATH"] += os.pathsep + pandoc_dir
    pypandoc.ensure_pandoc_installed(
        quiet=True,
        targetfolder=pandoc_dir,
        delete_installer=True,
    )


def setup(app):
    app.connect("builder-inited", ensure_pandoc_installed)

pypandoc 出现在 requirements.txt 文件中

这告诉 Sphinx 检查 pandoc 是否已经在系统路径上，如果它不可用，那么它将下载并安装一个副本到存储库的 docs/bin/pandoc 目录并将其添加到 PATH .

Answer 3

第一

pip uninstall pandoc

接下来，

conda install pandoc

只需在 Anaconda 提示符下执行（必要时重启内核），然后完成！

Answer 4

好吧，我让它在我的系统上运行：

• 从https://pandoc.org/installing.html下载并安装pandoc
• 启动新会话（cmd 或 power shell）
• 再次调用 sphinx make

就这么简单。希望你能得到它的工作！