如何强制Sphinx使用Python 3.x解释器

Question

我尝试为使用Python 3.x编写的项目创建文档.Sphinx是我想要使​​用的工具,根据官方网站,它的最新版本1.1.2与Python 3.1+兼容.我的操作系统是Archlinux,一个使用Python 3.2+作为默认Python包的Linux发行版.

安装和配置是直接的(easy_install -U Sphinx然后sphinx-quickinstall),我从未被要求在2.x或3.x Python解释器之间进行选择.但是当我要求Sphinx创建我的项目的文档时,我的代码就像我为Python 2.x编写它一样进行分析.

Sphinx是否已准备好使用Python 3.x？我犯了错误吗？

Answer 1

安装:使用pip为python3安装sphinx (像这样的pip3).

    pip3 install -U sphinx

构建:( Makefile linux/Mac)更改.

    SPHINXBUILD   = python -msphinx

在Makefile的上面一行中将python改为python3(或python3.x)之类的

   SPHINXBUILD   = python3 -msphinx

如果默认python指向2.x版python.

Answer 2

我来自未来（2020）。

我在让 Sphinx 与特定的 python 解释器和 Ubuntu 完美配合时遇到了问题。只是认为最新的答案可能会帮助其他在这里徘徊的人。

=====================================

因此，首先要了解的是，如果您使用自动构建/安装选项，您仍然应该仔细检查您是否得到了您认为应该得到的东西。

例如，运行（如Sphinx 文档顶部的建议）

apt install python3-sphinx

然后sphinx-quickstart在您想要构建自动文档的目录中运行即可。但是，它将使用 Sphinx 1.6.7（在撰写本文时，最新的 Sphinx 版本是 3.0.3），因为该存储库显然没有维护。然后，如果您想使用一些 Sphinx 扩展（例如sphinx-js，这就是我的情况），那么您可能会感到有点惊讶。

因此，我建议仅将这些自动打包安装用于简单的用例或测试或原型设计。

===========================================

更好的方法

使用 pip 安装 SPHINX（Py3 为 pip3）

pip3 install -U sphinx

现在您拥有最新的 pip3 版本，并且它正在与特定的已知解释器一起使用。您可以仔细检查pip3 list

初始化项目的自动文档

如果执行上述操作，sphinx-quickstart可能不起作用：找不到命令。我猜测它apt install会负责将一些脚本（例如 sphinx-quickstart）放入路径中。

但是你可以这样做：

python3 -m sphinx.cmd.quickstart 

在文档目录的根目录中。这将非常类似于 sphinx-quickstart。如果您想要更多功能，您可能需要向新创建的conf.py添加扩展。例如（有关详细信息，请参阅 Sphinx 的文档）：

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages']

构建你的文档

最后，make html如果以这种方式安装将无法开箱即用。但是，您可以改为启动完整命令：

[python 解释器] -m sphinx.cmd.build -b [构建器类型] [path-to-conf.py] [path-output-directoy]

举个例子：

python3 -m sphinx.cmd.build -b html /home/anonymous/PycharmProjects/DocstringDemo/docstrings /home/anonymous/PycharmProjects/DocstringDemo/docstrings/_build

这几乎就是 makefile 本身所做的事情。

现在你已经安装了带有特定解释​​器的 Sphinx

Answer 3

在Ubuntu上,python3-sphinx是一个单独的包.在我的情况下,我需要安装python3-sphinx:

sudo apt-get install python3-sphinx

你可以在一台机器上运行它们,但我只是删除了旧机器:

sudo apt-get remove python-sphinx

在此之后,我的旧makefile与我的Python 3代码一起工作得很好.

Answer 4

昨晚,当我遇到你的问题时,我遇到了同样的问题. - 我也在Arch.

我想问题可能是许多不同的事情,但对我来说解决方案是我python-distribute安装了Python 2版本的软件包,因此easy_install-2.7没有easy_install-3.2.

我相信在我的情况下python-distribute,我尝试先从pacman安装Sphinx(安装版本1.0.8)安装了错误的版本,因此卸载Sphinx以及随后所有不需要的依赖项pacman -Rsu python-sphinx,然后安装python-distribute得到我正确的版本easy_install,然后重新安装Sphinx with easy_install和Sphinx安装按预期工作.

如果你有其他依赖的东西,python-distribute那么这个过程可能会有所不同.但首先只是尝试python-distribute从那里删除和工作.

报废最后一部分.现在还太早了,我没想到!python2-distribute并且python-distribute是我认为可以共存的单独包装.因此,如果这是您的问题,您需要做的就是检查您是否python-distribute(不是"2"),如果没有安装它,然后确保您使用easy_install-3.2安装Sphinx.

希望这对你有所帮助.

Answer 5

我在Ubunut上也遇到了同样的问题.我不会使用Josh_P或Nicolas的回答,因为..

• 我不想改变我的PYTHON路径.
• 我不想卸载python-sphinx,因为我需要使用较旧的Projects.

所以我用这个名为的小脚本修复了它sphinx3-build:

#!/usr/bin/python3
# -*- coding: utf-8 -*-
"""
Same as /usr/bin/sphinx-build but with different
interpreter
"""

import sys

if __name__ == '__main__':
    from sphinx import main, make_main
    if sys.argv[1:2] == ['-M']:
        sys.exit(make_main(sys.argv))
    else:
        sys.exit(main(sys.argv))

它与sphinx-build相同,但使用不同的解释器.在Makefile中,我更改了以下行:

SPHINXBUILD   = sphinx3-build

现在将文件复制到该/usr/bin/文件夹:

sudo cp sphinx3-build /usr/bin/

这对我有用.您也可以将本地用于一个项目,只需将脚本放在与Makefile相同的文件夹中并设置SPHINXBUILD为 ./sphinx3-build.