Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.maint.python > #10233 > unrolled thread

Where to put docs of a -doc package for python 2 + 3 modules?

Back to article view | Back to linux.debian.maint.python

Contents

  Where to put docs of a -doc package for python 2 + 3 modules? "W. Martin Borgert" <debacle@debian.org> - 2018-03-12 11:20 +0100
    Re: Where to put docs of a -doc package for python 2 + 3 modules? Simon McVittie <smcv@debian.org> - 2018-03-12 11:40 +0100
      Re: Where to put docs of a -doc package for python 2 + 3 modules? "W. Martin Borgert" <debacle@debian.org> - 2018-03-12 14:30 +0100
    Re: Where to put docs of a -doc package for python 2 + 3 modules? Thomas Goirand <zigo@debian.org> - 2018-03-12 23:20 +0100
      Re: Where to put docs of a -doc package for python 2 + 3 modules? "W. Martin Borgert" <debacle@debian.org> - 2018-03-12 23:40 +0100
        Re: Where to put docs of a -doc package for python 2 + 3 modules? Ghislain Vaillant <ghisvail@gmail.com> - 2018-03-13 00:40 +0100
          Re: Where to put docs of a -doc package for python 2 + 3 modules? Ben Finney <bignose@debian.org> - 2018-03-13 08:20 +0100
          Re: Where to put docs of a -doc package for python 2 + 3 modules? Thomas Goirand <zigo@debian.org> - 2018-03-13 09:20 +0100
            Re: Where to put docs of a -doc package for python 2 + 3 modules? Ghislain Vaillant <ghisvail@gmail.com> - 2018-03-13 10:00 +0100
            Re: Where to put docs of a -doc package for python 2 + 3 modules? "W. Martin Borgert" <debacle@debian.org> - 2018-03-13 10:00 +0100
            Re: Where to put docs of a -doc package for python 2 + 3 modules? Ole Streicher <olebole@debian.org> - 2018-03-13 10:30 +0100
              Re: Where to put docs of a -doc package for python 2 + 3 modules? Thomas Goirand <zigo@debian.org> - 2018-03-13 14:10 +0100

#10233 — Where to put docs of a -doc package for python 2 + 3 modules?

Hi,

policy (12.3) says, that putting the contents of package-doc
into /usr/share/doc/package/ (main package) is preferred over
/usr/share/doc/package-doc/. debhelper detects the Python 2
package as main package. One can override this to the path for
the Python 3 package, but both feels wrong to me. Even if we
drop Python 2 at some point, maybe then there is Python 4 or
PyPy. I tend to stay with the traditional path, and ignore
the preference of our beloved policy. Not without first
consulting this very mailing list, of course. Opinions?

TIA & Cheers

[toc] | [next] | [standalone]

#10234

On Mon, 12 Mar 2018 at 11:16:16 +0100, W. Martin Borgert wrote:
> policy (12.3) says, that putting the contents of package-doc
> into /usr/share/doc/package/ (main package) is preferred over
> /usr/share/doc/package-doc/. debhelper detects the Python 2
> package as main package. One can override this to the path for
> the Python 3 package, but both feels wrong to me. Even if we
> drop Python 2 at some point, maybe then there is Python 4 or
> PyPy.

In python-mpd-doc and python-dbus-doc, I installed the real documentation
files in /u/s/d/python-*-doc, but placed symlinks to them in both
/u/s/d/python-* and /u/s/d/python3-*. Perhaps that's a reasonable way
to achieve the spirit of the Policy §12.3 recommendation while not
privileging one of Python 2, Python 3, PyPy, etc. over the others?

    smcv

[toc] | [prev] | [next] | [standalone]

#10235

Quoting Simon McVittie <smcv@debian.org>:
> In python-mpd-doc and python-dbus-doc, I installed the real documentation
> files in /u/s/d/python-*-doc, but placed symlinks to them in both
> /u/s/d/python-* and /u/s/d/python3-*. Perhaps that's a reasonable way
> to achieve the spirit of the Policy §12.3 recommendation while not
> privileging one of Python 2, Python 3, PyPy, etc. over the others?

Nice idea, I'll do the same. Thanks!

[toc] | [prev] | [next] | [standalone]

#10236

On 03/12/2018 11:16 AM, W. Martin Borgert wrote:
> Hi,
> 
> policy (12.3) says, that putting the contents of package-doc
> into /usr/share/doc/package/ (main package) is preferred over
> /usr/share/doc/package-doc/. debhelper detects the Python 2
> package as main package. One can override this to the path for
> the Python 3 package, but both feels wrong to me. Even if we
> drop Python 2 at some point, maybe then there is Python 4 or
> PyPy. I tend to stay with the traditional path, and ignore
> the preference of our beloved policy. Not without first
> consulting this very mailing list, of course. Opinions?
> 
> TIA & Cheers

I also asked myself this question for python3 only packages.

I used to have:
- python-foo
- python3-foo
- python-foo-doc

But what now that python-foo is gone? Should I rename the doc package?
Please share your thoughts,

Cheers,

Thomas Goirand (zigo)

[toc] | [prev] | [next] | [standalone]

#10237

On 2018-03-12 23:15, Thomas Goirand wrote:
> But what now that python-foo is gone? Should I rename the doc package?

No, but that's just my gut feeling.

[toc] | [prev] | [next] | [standalone]

#10238

2018-03-12 22:30 GMT+00:00 W. Martin Borgert <debacle@debian.org>:
> On 2018-03-12 23:15, Thomas Goirand wrote:
>> But what now that python-foo is gone? Should I rename the doc package?
>
> No, but that's just my gut feeling.

Definitely not, indeed. The python- prefixes in python-foo and
python-foo-doc are not exactly equivalent.
The former usage refers to the Python 2 interpreter, the latter refers
to Python *the language*.

It's unfortunate our naming convention did not explicitly separate
between both as Arch packages do,
whereby `python` is used for source package and `python2` for binary
packages targeting CPython 2.x.

Imo, we should just make it clear in policy that source packages
should be named `foo` or `python-foo`,
and corresponding doc packages should be named `foo-doc` or `python-foo-doc`.

Ghis

[toc] | [prev] | [next] | [standalone]

#10239

Ghislain Vaillant <ghisvail@gmail.com> writes:

> Definitely [do not name the documentation package ‘python3-foo-doc’],
> indeed. The python- prefixes in python-foo and python-foo-doc are not
> exactly equivalent. The former usage refers to the Python 2
> interpreter, the latter refers to Python *the language*.

Yes, that's how I understand the distinction. Thank you for expressing that.

> It's unfortunate our naming convention did not explicitly separate
> between both as Arch packages do, whereby `python` is used for source
> package and `python2` for binary packages targeting CPython 2.x.

Yes.

Another point: The name of the documentation package should not depend
on whether there is a Python 2 library package. So, the presence or
absence of ‘python-foo’ should not change the name of ‘python-foo-doc’.

> Imo, we should just make it clear in policy that source packages
> should be named `foo` or `python-foo`, and corresponding doc packages
> should be named `foo-doc` or `python-foo-doc`.

+1.

-- 
 \       "Those who will not reason, are bigots, those who cannot, are |
  `\        fools, and those who dare not, are slaves." —“Lord” George |
_o__)                                                Gordon Noel Byron |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#10240

On 03/13/2018 12:29 AM, Ghislain Vaillant wrote:
> Imo, we should just make it clear in policy that source packages
> should be named `foo` or `python-foo`,
> and corresponding doc packages should be named `foo-doc` or `python-foo-doc`.

Very often, "foo" is already taken by another package, and we have to
fallback to python-foo. Think about generic libs for compression,
images, network standards...

Which is why I think we should have standardize on python-foo for the
source package (which is what I do).

Cheers,

Thomas Goirand (zigo)

[toc] | [prev] | [next] | [standalone]

#10241

Le mardi 13 mars 2018 à 09:18 +0100, Thomas Goirand a écrit :
> On 03/13/2018 12:29 AM, Ghislain Vaillant wrote:
> > Imo, we should just make it clear in policy that source packages
> > should be named `foo` or `python-foo`,
> > and corresponding doc packages should be named `foo-doc` or
> > `python-foo-doc`.
> 
> Very often, "foo" is already taken by another package, and we have to
> fallback to python-foo. Think about generic libs for compression,
> images, network standards...

Agreed.

> Which is why I think we should have standardize on python-foo for the
> source package (which is what I do).

Same here.

Do you think we should be recommending the use of `python-foo` in the
DPMT packaging policy? This could help avoiding ITPs for `python3-bar`.

Ghis

[toc] | [prev] | [next] | [standalone]

#10242

Quoting Thomas Goirand <zigo@debian.org>:
> Which is why I think we should have standardize on python-foo for the
> source package (which is what I do).

Same here, even if foo is not yet taken.

Save the environment, do not pollute the global packages namespace! :~)

[toc] | [prev] | [next] | [standalone]

#10243

Thomas Goirand <zigo@debian.org> writes:
> On 03/13/2018 12:29 AM, Ghislain Vaillant wrote:
>> Imo, we should just make it clear in policy that source packages
>> should be named `foo` or `python-foo`,
>> and corresponding doc packages should be named `foo-doc` or `python-foo-doc`.
>
> Very often, "foo" is already taken by another package, and we have to
> fallback to python-foo. Think about generic libs for compression,
> images, network standards...
>
> Which is why I think we should have standardize on python-foo for the
> source package (which is what I do).

I disagree. Often packages already signalize their Python origin:
astropy, sunpy, pyephem etc. Or relate to pytest (pytest-mpl for
example). Or provide a Python package just as one of many other packages
(plplot). Prefixing them with "python-" increases useless redundancy,
and makes it harder for external people to find the package.

I would deviate from the rule of thumb "stick with the upstream name
unless there is a (potential) conflict". And if there is a conflict,
talk to upstream to find a solution -- it is quite probable that it will
lead to file conflicts as well (tools/apps in /usr/bin).

Best

Ole

[toc] | [prev] | [next] | [standalone]

#10245

On 03/13/2018 10:11 AM, Ole Streicher wrote:
> and makes it harder for external people to find the package.

I don't see how. A query to https://packages.debian.org/foo will also
show python-foo, and same with apt-cache search. So how is it harder?

Cheers,

Thomas Goirand (zigo)

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.maint.python

csiph-web