How best to handle tools which support multiple Python runtimes

[Avram Lubkin]

I'm a co-maintainer for the python-sphinx package. There's a bug [1] I'd
like to address, but I'd like some input on what I was thinking. There was
some discussion about this on FPC ticket [2], but nothing workable really
came out of that. I also attempted to get input [3] from the Sphinx
community, but didn't receive a response.

For background, python-sphinx is available for both Python2 and Python3. It
is primarily a library, but provides four commands for convenience:
sphinx-build, sphinx-quickstart, sphinx-apidoc, sphinx-autogen. Here's an
example of how these commands are currently made available to the user:

/usr/bin/sphinx-build -> sphinx-build-2
/usr/bin/sphinx-build-2 -> sphinx-build-2.7
/usr/bin/sphinx-build-2.7 (#!/usr/bin/python2)
/usr/bin/sphinx-build-3 -> sphinx-build-3.4
/usr/bin/sphinx-build-3.4 (#!/usr/bin/python3)

It should be noted, all of these commands are just used to call entry
points and don't have any of their own logic. Here are their equivalents:

sphinx-build            python -m sphinx
sphinx-quickstart    python -m sphinx.quickstart
sphinx-apidoc         python -m sphinx.apidoc
sphinx-autogen       python -m sphinx.ext.autosummary.generate

Sphinx itself isn't Python version specific and maintains compatibility
regardless of what Python version you are using or if you switch back and
forth. Potentially there are some Sphinx extensions that are Python version
dependent, but I am not aware of any.

Use cases for Sphinx are all over the place. For example, I rarely use the
commands and call sphinx through setuptools 99% of the time. Other people
use the commands exclusively, and still others use the makefile created by
sphinx-quickstart as their primary way to call it.

It's this last one is where we are seeing the biggest problem and is
described in the bug. Essentially, sphinx-quickstart-3 is used to create a
makefile which lists sphinx-build as the build command. But sphinx-build is
currently linked to the python2 version, which may not be expected, and
won't necessarily be installed.

It was suggested the makefile should be changed so the Python version that
was used for sphinx-quickstart should be used for sphinx-build.
Unfortunately, that would make the file less portable.

I have two possible fixes:

The first would be to decouple the commands from the libraries. Since the
package name sphinx is already taken by the search engine, something like
python-sphinx-bin may be appropriate. Once separated, the command would
default to python3 since the packaging guidelines say it Python 3 versions
should be preferred when equivalent.

The second option would be to retain the multiple versions, but to manage
the links with alternatives so the unversioned commands will default to
whatever version is installed and again, Python 3 would be preferred if
both were installed.

Does anyone have any preferences, thoughts or alternative approaches?

Avram

[1] https://bugzilla.redhat.com/show_bug.cgi?id=1321413
[2] https://fedorahosted.org/fpc/ticket/612
[3] https://groups.google.com/forum/#!topic/sphinx-dev/vdFeOEj4EKg