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

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

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 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.

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

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 6

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