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

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