Re: [gentoo-dev] Should Sphinx really depends on PYTHON_COMPAT/PYTHON_USEDEP for `dev-python/*` ebuilds?

[Michał Górny]

Hi,

Few janitorial notes for a start:

1. please fix your line wrapping since your messages are wrapped twice
now, and it's really hard to read with single words on every second
line;

2. hardcore Python topics belong on gentoo-python@ but I guess we'll
continue here,

3. please keep your messages brief. The first three paragraphs tell
a thing that could be told in one sentence.

On czw, 2017-05-11 at 11:47 +0700, Alex Turbov wrote:
> Thus generally specking, Sphinx dependencies have no relations to `DEPEND`
> of particular
> `dev-python/*` ebuilds! So, in simple case there is should be enough to
> specify
>
>     DEPEND=( doc? ( dev-python/sphinx ) )
>
> for that ebuilds. In some rare cases (like
> https://bugs.gentoo.org/show_bug.cgi?id=618162)
> Sphinx could use some extensions (plugins) and they also have no any
> relation to `PYTHON_COMPAT`
> of particular `dev-python/*` ebuild! That plugins to work need just the
> same `PYTHON_TARGETS`
> as used to build Sphinx. Unfortunately I can't find appropriate helper
> function(s) in any
> currently present Python reelated eclasses (or am I miss smth?), so I used
> the following
> dependency spec:
>
>     DEPEND=( doc?
>         || (
>                 (
>                     dev-python/sphinx[python_targets_python2_7]
>                     # NOTE This packages provide extensions for Sphinx
>                     dev-python/rst-linker[python_targets_python2_7]
>                     dev-python/jaraco-packaging[python_targets_python2_7]
>                 )
>                 (
>                     dev-python/sphinx[python_targets_python3_5]
>                     dev-python/rst-linker[python_targets_python3_5]
>                     dev-python/jaraco-packaging[python_targets_python3_5]
>                 )
>                 (
>                     dev-python/sphinx[python_targets_python3_6]
>                     dev-python/rst-linker[python_targets_python3_6]
>                     dev-python/jaraco-packaging[python_targets_python3_6]
>                 )
>             )
>       )

You can't use python_targets directly since it will break when the old
implementations are disabled (and also make it PITA for others to add
new impls).

>
> So, my questions are:
>
> 0. am I missed smth? (and there are some other cases, I don't know about)
> 1. am I missed smth? (and there are some helper functions exist in eclasses
> to expess that kind
>    of dependencies)
> 2. I think it would be nice to have some support for Sphinx in eclasses to
> simplify ebuilds writing
>    (if #1 is false)
>
> Ideas/comments/opinions are really welcome...

Long story short, it's not worth the effort.

Yes, most of the time people specify PYTHON_USEDEP on sphinx needlessly.
 There are two other major cases when you need it though:

1. things like autointerface that interface with packages' code,

2. and packages calling sphinx via 'python /usr/bin/sphinx ...' (i.e.
requiring impl match between python in use and sphinx).

However, tracking the other uses down and figuring them is not worth
the effort. In the end, someone will probably add it back thinking
someone must've missed it. It's too hard to get it right.

In fact, I'm personally leaning towards not building docs at all
in ebuilds. It's practically a wasted effort since most of the time
users read docs online anyway.

Building Sphinx with less implementations than its reverse dependencies
is a corner case. It's not really worth spending hours making sure
depends are 100% strictly correct. The more important goal is to have
things working reliably, and overspecified deps are reliable, i.e.
packages won't fail to build because of them.

-- 
Best regards,
Michał Górny