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

Question

问题

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

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 文件中替换pandocwith来告诉它从源代码构建git+git://github.com/jgm/pandoc#egg=pandoc，但这不起作用（请参阅下文了解我的文件的外观）。我可以轻松地在本地机器上安装 pandoc，但无法通过我的虚拟环境或 readthedocs 中的 requirements.txt 文件进行安装。

我的一些文件

这是我的requirements.txt文件：

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

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

阅读文档.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

环境.yaml

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

总之

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

非常感谢任何人的建议！

Answer 1

目前， PyPI 页面上对 pandocs 的解释还不是很好，但 pandoc 实际上是用 Haskell 编写的，而不是 Python。您可以安装的 python pandoc 包pip install pandoc不附带 pandoc 的可执行副本，它只是一个包装器，用于在 python 中提供与 pandoc 的绑定。它通过对 pandoc 的系统副本进行 shell 调用来实现此目的，因此您需要单独将实际 pandoc 可执行文件的副本安装到您​​的系统中，以便 python 绑定有可以绑定的内容！

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

sudo apt install pandoc
pip install pandoc

尽管您可以在本地系统上执行此操作，但这并不是使其在 readthedocs 上运行的可行解决方案。

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

conda install pandoc

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

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

据说 py-pandoc 是通过 python 界面安装 pandoc 的一站式商店。我认为你只需要执行pip install py-pandocorconda install pandoc即可立即生效，尽管由于缺乏文档我不确定。

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

from inspect import getsourcefile

# Get path to directory containing this file, conf.py.
DOCS_DIRECTORY = os.path.dirname(os.path.abspath(getsourcefile(lambda: 0)))

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 dir containing pandoc binary to the PATH environment variable
    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 中。

这种方法的优点是它应该是通用的，使任何下游用户都可以构建文档。虽然对于 readthedocs 构建，您可以控制 pandoc 是否与 conda 一起安装，但您不能保证每个想要构建文档的用户都以这种方式安装了 pandoc python 软件包，也不能保证他们的系统上安装了 Haskell pandoc 软件包。

Answer 2

我遇到了同样的问题。

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

看来pandoc通过安装pip或使用安装是有区别的conda。

请尝试以下操作：

pip uninstall pandoc
conda install pandoc

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

另一方面，如果您使用poetry，您也可能会遇到相同的错误消息，即PandocMissing。

Windows：通过 Windows 安装程序
安装： https://pandoc.org/installing.html。Pandoc

Linux（使用 Ubuntu 2204 测试）：
sudo apt install pandoc

Answer 3

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

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

就那么简单。希望你能让它发挥作用！