How to force Sphinx to use Python 3.x interpreter

Question

I try to create documentation for a project written with Python 3.x. Sphinx is the tool I want to use and, according to the official site, its last version 1.1.2 is compatible with Python 3.1+. My OS is Archlinux, a Linux distribution which uses Python 3.2+ as the default Python package.

The installation and configuration is straight forward (easy_install -U Sphinx then sphinx-quickinstall) and I was never asked to choose between the 2.x or 3.x Python interpreter. But when I ask Sphinx to create the documentation of my project, my code is analyzed as if I wrote it for Python 2.x.

Is Sphinx ready for Python 3.x? Did I make a mistake?

Answer 1

Installation: Install sphinx with pip for python3(pip3 like that).

    pip3 install -U sphinx

Building: Makefile(linux/Mac) changes.

    SPHINXBUILD   = python -msphinx

In above line in Makefile change python to python3(or python3.x) like

   SPHINXBUILD   = python3 -msphinx

if default python is pointing to 2.x version python.

Answer 2

On Ubuntu, python3-sphinx is a separate package. In my case, I needed to install python3-sphinx:

sudo apt-get install python3-sphinx

You can probably run both on a machine, but I just removed the old one:

sudo apt-get remove python-sphinx

My old makefile worked just fine with my Python 3 code after this.

Answer 3

I'm from the future (2020).

I've had issues making Sphinx play nicely with a specific python interpreter and Ubuntu. Just thought an up to date answer might help others wandering here.

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

So, the first thing to understand is that if you use the automated build/installation option, you should still double-check that you're getting what you think you should.

For instance, running (as suggested at the top of Sphinx's doc)

apt install python3-sphinx

and then running sphinx-quickstart in a directory where you want to build the auto-doc will work. However, it will use Sphinx 1.6.7 (at the time of writing the latest Sphinx version is 3.0.3), since the repo is apparently not maintained. Then if you want to use some Sphinx extensions (like sphinx-js, which was my case) then you may be in for a bit of a surprise.

So I would recommend using those automated packaged install only for straightforward use cases or testing or prototyping.

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

A better approach

Install SPHINX using pip (pip3 for Py3)

pip3 install -U sphinx

Now you have the lastest pip3 release and it is working with a specific, known interpreter. You can double-check with pip3 list

Init you project's autodoc

If doing the above, sphinx-quickstart may not work: command not found. I am guessing that the apt install takes care of putting some scripts, such as sphinx-quickstart, in the path.

However you can do:

python3 -m sphinx.cmd.quickstart 

in the root of your documentation's directory. This will act much like sphinx-quickstart. If you want the more features, you may need to add extensions to the newly created conf.py. For exemple (see Sphinx's doc for details):

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

Building your doc

Then finally, make html if installed this way will not work out of the box. However, you can instead launch the full command instead:

[python interpreter] -m sphinx.cmd.build -b [builder type] [path-to-conf.py] [path-output-directoy]

For exemple:

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

Which is pretty much what the makefile itself does.

So now you have Sphinx installed with a specific interpreter

Answer 4

I had this exact same problem last night, when I came across your question. — I am also on Arch.

I guess the problem could be a number of different things, but the solution for me was that I had the Python 2 version of the python-distribute package installed and therefore had easy_install-2.7 not easy_install-3.2.

I believe in my case the wrong version of python-distribute was installed by my attempt to previously install Sphinx from pacman (which installs version 1.0.8), so uninstalling Sphinx and all subsequently unneeded dependencies pacman -Rsu python-sphinx and then installing python-distribute got me the right version of easy_install, then reinstalling Sphinx with easy_install and the Sphinx installation works as expected.

If you have other things that depend on python-distribute then the process may be a little different. But start by just trying to remove python-distribute and work from there.

Scrap that last part. It's too early in the morning and I wasn't thinking straight! python2-distribute and python-distribute are seperate packages which I believe can co-exist. So, if this is your problem all you need to do is check you have python-distribute (not "2"), if not install it, and then ensure you use easy_install-3.2 to install Sphinx.

Hope this helps you.

Answer 5

I'm on Ubunut and had the same problem. I won't use Josh_P or Nicolas answer because..

• I don't want to change my PYTHON path.
• I don't want to uninstall python-sphinx because I need it with older Projects.

So i fixed it with this little script called 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))

It's the same as sphinx-build but with a different interpreter. In the Makefile I changed the following line:

SPHINXBUILD   = sphinx3-build

Now copy the file to the /usr/bin/ folder:

sudo cp sphinx3-build /usr/bin/

This worked for me. You could also use it locally for one project only by placing the script into the same folder as the Makefile and set SPHINXBUILD to ./sphinx3-build.

Answer 6

A similar solution to those already offered is to put the call to sphinx.main() right into the SPHINXBUILD variable in the Makefile:

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

The sphinx-generated "User-friendly check for sphinx-build" block of code fails then so I just removed it. This solution was preferable to me since it didn't require a separate script nor the removal of any python installation or sphinx module.

Answer 7

When I searched for an answer, this is the site that came up over and over. I'm thinking the answer is not easy to find because everyone else understands sphinx better than I can figure out. But if any is still searching for an answer, this is what eventually I ended up with:

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 install Sphinx

The key was I was missing the fact that there was a pip3. I also update the system before adding a package as habit.

Answer 8

It seems that Sphinx is installed only with Python-2 support. Although there are various ways to install Sphinx for python3, just use virtualenv to create a custom environment that uses python3 by default.

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

And inside the virtualenv install Sphinx:

pip install Sphinx

As a bonus, this approach allows you to create custom environments for different projects.

PS. You might want to consider using virtualenvwrapper.

Answer 9

I think Sphinx simply uses the "python" command as interpreter. But according to the Makefile, you can specify your own with the PYTHON option, when running make for installation.