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?

Solution 1

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.

Solution 2

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.

Solution 3

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.

Solution 4

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.

Solution 5

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

View more solutions

Comments

[suizokukan]

Thank you for your answer; make html should(?) probably call python, id est, on my system, Python 3.2.2 - and that's exactly what I expect from Sphinx. But the result I get shows that another interpreter is called (python2 ?) even if I don't understand why.

[Nicolas]

Write in a terminal ls -l /usr/bin/python, it will print your default interpreter version.

[suizokukan]

Thank you for the tip but ls -l /usr/bin/python shows me that /usr/bin/python is linked to python3, id est on my system, to Python 3.2.2.

[Nicolas]

If you're sure the interpreter is Python 2.x (have you verified if another version of Python is installed btw?), you can install Sphinx again, setting the PYTHON option to python3 (see the easy_install doc).

[suizokukan]

Thank you for this idea. You say "there are various ways to install Sphinx for python3" : can you give me some explanations since I can't use - for the moment - virtualenv ?

[plaes]

@suizokukan Well, it depends on the platform and its distro. For example Gentoo GNU/Linux supports parallel installations of Python out of the box. It also gives version prefixes to the executable tools (I currently have Python-2.7 and Python-3.2 enabled on my machine and therefore installed created two easy-install commands : easy-install-2.7 and easy-install-3.2). So what platform/distro are you using?

[suizokukan]

I'm using an (up-to-date) Archlinux; on this distribution the command python is linked to Python 3.2.2.

[stevosn]

Thanks for that! This works fine! I thought switching the general /usr/bin/python symbolic link from /usr/bin/python2 to /usr/bin/python3 was a good idea, since I am only using python3 - well, it wasn't.. other progs then produced errors due to wrong python syntax.. ^^ That's a neater solution.

[oarfish]

This unfortunately does nothing for me.

[oarfish]

On macOS, uninstalling version 2.7 and only installing 3.5 doesn't do anything.

[oarfish]

Explicitly setting the interpreter doesn't do anything on macOS.

[John]

@oarfish a very similar command could be used in the make.bat file if you are on windows.

[oarfish]

Forgot to mention I'm on OSX.

[Eyshika]

this doesnt work even for OSX, gives error for >sphinx has no attribute 'main'

[Kiteloopdesign]

Thanks for this, it made the trick. The only I needed to do is NOT to run python3 -m sphinx.cmd.quickstart since there is already a conf.py file on my root