[Python-modules-team] Bug#815631: sphinx: Use alternatives to provide scripts under /usr/bin

[Kevin Murray]

Hi Dmitry,

Thanks for your advice.

On 10:19 23/02, Dmitry Shachnev wrote:
> Hi Kevin,
> 
> On Tue, Feb 23, 2016 at 02:34:11PM +1100, Kevin Murray wrote:
> > I have recently needed to use a python3-only sphinx build process on a
> > system with both python-sphinx & python3-sphinx co-installed. IMHO
> > co-installation could be a little cleaner and easier if sphinx:
> > 
> > - Used update-alternatives to provide /usr/bin/sphinx-* in a
> >   configurable way. (e.g similar to how docutils handles this problem). This
> >   could use the current script installation path under
> >   /usr/share/sphinx/scripts/python*/
> 
> Let me quote Jakub Wilk, who wrote the current implementation:
> 
>   The alternatives mechanism is only suitable if both commands are compatible,
>   i.e. their behavior doesn't vary with Python version. This is the case for
>   rst2html and friends, but no so much for sphinx-build. The problem is that
>   sphinx-build can import 3rd-party Python code, which is not necessarily
>   compatible with both Python 2 and 3.
> 

Ah, that's something I didn't consider. Good point.

> > - Or, installed binaries under /usr/bin with the suffix '3', i.e. install
> >   /usr/bin/sphinx-build3. (modelled after pip/pip3 & nosetests/nosetests3
> >   and other similar examples)
> 
> The name of sphinx-build command is hardcoded in too many places (i.e. the
> Makefiles generated by Sphinx use it). Also, I don't much like the foo/foo3
> naming because there is a better way: pythonX[.Y] -m sphinx allows one to
> call sphinx-build with *any* Python version (not necessarily the default one).
> 

Ah yes, that's true about hardcoding. This is actually why I need this:
hardcoded occurrences of sphinx-build in makefiles that aren't in python
projects but use (and only work with) python3 packages. And thanks for the tip
about python -m sphinx, I hadn't considered that. Though for the current use
case still means patching a makefile, in which case I'll just include the full
path to the installed script under /usr/share/sphinx.

> > - Or, a combination of both these, where python-sphinx and
> >   python3-sphinx install /usr/bin/sphinx-*{2,3} respectively, and
> >   update-alternatives is used to provide /usr/bin/sphinx-* without
> >   prefix.
> 
> See above.
> 
> > P.S., I know one can always do /usr/share/sphinx/scripts/python3/sphinx-build
> > as a workaround.
> 
> What is exactly your problem? Does Python 2 sphinx not work with your code?
> Can you use python3 -m sphinx there? Or maybe use setuptools' build_sphinx
> command?

The problem was to use python3-sphinx from a Makefile (not an auto-generated
sphinx-quickstart one) without patching the makefile. Given your descriptions
above, I think that there are better ways of solving this problem than what I
proposed.

*However*, there is a supplementary issue: AFAICT, which package provides the
/usr/bin/sphinx-* scripts depends on the order of installation. To me this
sounds a little off, but I'm not sure. What is your opinion of this?


Cheers,
K


---
Kevin Murray
0xA4B4EE6A
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/python-modules-team/attachments/20160223/fc4a6b2f/attachment.sig>