Question

我尝试为使用Python 3.x编写的项目创建文档。 Sphinx是我要使用的工具，根据official site，其最后一个版本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 （ pip3 ）安装sphinx。

    pip3 install -U sphinx

构建： Makefile（linux / Mac）更改。

    SPHINXBUILD   = python -msphinx

在Makefile的上一行中将 python 更改为 python3（或python3.x），如

   SPHINXBUILD   = python3 -msphinx

如果默认python指向2.x版本蟒。

Answer 2

在Ubuntu上，python3-sphinx是一个单独的包。就我而言，我需要安装python3-sphinx：

sudo apt-get install python3-sphinx

你可以在一台机器上运行，但我刚删除了旧机器：

sudo apt-get remove python-sphinx

我的旧makefile在我的Python 3代码之后运行得很好。

Answer 3

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

我想这个问题可能有很多不同之处，但我的解决方案是我安装了python-distribute软件包的Python 2版本，因此easy_install-2.7没有{{1} }。

我相信在我的情况下，我尝试先从pacman安装Sphinx（安装版本1.0.8）时安装了错误版本的easy_install-3.2，因此卸载Sphinx以及随后所有不需要的依赖项python-distribute然后安装pacman -Rsu python-sphinx让我得到python-distribute的正确版本，然后用easy_install重新安装Sphinx，并且Sphinx安装按预期工作。

~~如果您有其他依赖easy_install的事情，那么这个过程可能会有所不同。但首先只是尝试删除python-distribute并从那里开始工作。~~

报废最后一部分。现在太早了，我没想到！ python-distribute和python2-distribute是我认为可以共存的独立包。因此，如果这是您的问题，您需要做的就是检查您是否python-distribute（而不是“2”），如果没有安装它，请确保使用python-distribute安装Sphinx。

希望这会对你有所帮助。

Answer 4

我在Ubunut上遇到了同样的问题。我不会使用 Josh_P 或 Nicolas 的答案，因为..

我不想改变我的PYTHON路径。
我不想卸载python-sphinx，因为我需要使用较旧的项目。

所以我用这个名为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。

Answer 5

与已经提供的解决方案类似的解决方案是将对sphinx.main（）的调用直接放入Makefile中的SPHINXBUILD变量中：

SPHINXBUILD   = python3 -c "import sys,sphinx;sys.exit(sphinx.main(sys.argv))"

sphinx生成的“用户友好检查sphinx-build”代码块失败，所以我只是将其删除了。这个解决方案比我更好，因为它不需要单独的脚本，也不需要删除任何python安装或sphinx模块。

Answer 6

我来自未来（2020年）。

我在使Sphinx与特定的python解释器和Ubuntu兼容方面遇到问题。只是认为最新的答案可能会帮助其他人在这里徘徊。

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

因此，首先要了解的是，如果您使用自动构建/安装选项，则仍应再次检查您是否正在获得应有的功能。

例如，正在运行（如Sphinx's doc顶部的建议）

apt install python3-sphinx

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

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

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

更好的方法

使用pip（对于Py3为pip3）安装SPHINX

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 7

似乎Sphinx仅支持Python-2。虽然有多种方法可以为python3安装Sphinx，但只需使用virtualenv创建一个默认使用python3的自定义环境。

virtualenv -p /path/to/python-3 foo

在virtualenv中安装Sphinx：

pip install Sphinx

作为奖励，此方法允许您为不同的项目创建自定义环境。

PS。您可能需要考虑使用virtualenvwrapper。

Answer 8

当我搜索答案时，这是一遍又一遍的网站。我认为答案并不容易找到，因为其他人都比我能想到的更能理解狮身人面像。但如果有人仍然在寻找答案，那么这最终是我最终的结果：

sudo apt-get update

sudo apt-get install python3

sudo apt-get install sqlite3

sudo apt-get install idle3

sudo apt-get install python3-pip

sudo apt-get install python3-docutils

sudo apt-get install python3-jinja2

sudo apt-get install python3-pygments

sudo pip3安装Sphinx

关键是我错过了有一个pip3的事实。我还在添加包作为习惯之前更新系统。

Answer 9

我认为Sphinx只是使用“python”命令作为解释器。但是根据Makefile，您可以在运行make进行安装时使用PYTHON选项指定自己的选项。

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

9 个答案:

更好的方法

初始化项目的自动文档

构建文档