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