Path: csiph.com!feeder.erje.net!2.eu.feeder.erje.net!feed.usenet.farm!feeder3.usenet.farm!eternal-september.org!feeder.eternal-september.org!aioe.org!bofh.it!news.nic.it!robomod
From: PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr>
Newsgroups: linux.debian.maint.python
Subject: RE:building manpages via setup.py
Date: Wed, 02 Aug 2017 14:30:02 +0200
Message-ID: <ua0WK-1ph-7@gated-at.bofh.it>
References: <u9GEH-5cQ-19@gated-at.bofh.it> <u9Hr4-5Jr-23@gated-at.bofh.it> <u9W6J-6Ni-3@gated-at.bofh.it> <u9Wgq-6Qo-9@gated-at.bofh.it> <u9WzL-6Xn-9@gated-at.bofh.it> <u9WzL-6Xn-7@gated-at.bofh.it> <u9WzM-6Xn-25@gated-at.bofh.it> <u9X2O-7mD-23@gated-at.bofh.it> <u9X2O-7mD-21@gated-at.bofh.it> <u9Xmb-7tc-27@gated-at.bofh.it> <u9Xmb-7tc-37@gated-at.bofh.it> <u9XYS-7WK-7@gated-at.bofh.it> <u9Y8x-83f-13@gated-at.bofh.it> <ua0WK-1ph-9@gated-at.bofh.it> <u9ZnZ-it-21@gated-at.bofh.it>
Old-Return-Path: <frederic-emmanuel.picca@synchrotron-soleil.fr>
Thread-Topic: building manpages via setup.py
Thread-Index: AdMKnYeNbtHGA2ChRMa/5+FgMHXlSAALU42AACRWRyD//+WzAIAAIkd1///kXwCAAAEXAIAAJXaV///iEoCAACJ29f//4toAAAS5p7UAAwPEAAABSiC/AAR9KgAAAnV++A==
Accept-Language: fr-FR, en-US
Content-Language: fr-FR
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Approved: robomod@news.nic.it
Lines: 94
Organization: linux.* mail to news gateway
Sender: robomod@news.nic.it
Xref: csiph.com linux.debian.maint.python:9678

> The snippet you quoted is not specific to extension modules but to the
> use of the autodoc feature, which requires the modules to be in the
> PYTHONPATH. The `sys.path.insert` hack is just here so that you don't
> have to specify PYTHONPATH yourself when running the upstream Makefile.

I just says that this snipset is in the conf.py and I yes we need this for =
autodoc.

> I don't understand how setup.py / build options are affecting the Sphinx
> documentation. You are supposed to either call the generator manually
> via sphinx-build (which the style guide recommends), or using the
> upstream Makefile (which upstream often does).

autodoc introspect the module so you need a working modules from python, wh=
cih is avhieved via the right PYTHONPATH.
So, during the build phase you can gives  options on the python setup.py co=
mmand line.
This has an effect on the location where the module  and the extensions are=
 built.

build seems to be the default location BUT when we use pybuild it is under =
.pybuild

So the default PYTHONPATH does not work.

there is no way for sphinx to know where the module and its extensions are =
excepty by providing the right PYTHONPATH.

Except if sphinx would provide a build_sphinx command whcih take care of th=
is problem and take into account the parameters of the setup.py.

> As far as reliability is concerned, my reference here is upstream. If
> upstream can produce the docs, then I should be able to do it too. And
> they don't have pybuild for that.

Yes but sometime there si some hack done by the upstream in conf.py or setu=
p.py
in order to look for the module at the standards path (under build/) which =
doesn not work with pybuild.

> Why would you build the docs for each supported Python version,
> considering you'll end up shipping only one instance of the generated
> HTML? I am probably missing something here.

I use this as a sort of unit test. And it is interesting because I catche a=
 bunch of python2/python3 issues like this.
Then I can find issues between sphinx running on python2 or python3.

This is at least a good way to check thaht all the modules can be laoded.

autodoc is interesting for this.

> You might as well generate the docs just once with the default Python 2
> or Python 3 interpreter, the same way you would do without extension
> modules, no?

> Pardon my insistence, but I really fail to understand what issues you
> are referring to.

incompatibilities vetween python2 and python 3 code.
peoples trie to  write code python2 and python3 compatible but this is not =
thaht easy...

> More than I expected, indeed.

> And amongst these 643 packages, how many have such large build times
> that the overhead of an additional inplace call would be considered
> prohibitive, I wonder?

I do not know, I just think that we should be able to automatically generat=
e packages for python modules from pip in order to
reduce the effort of pacakging, So there should be only one way to build th=
e documentation , manpages.
Escpecillay wheren there is extensions.


> Besides, the docs will typically be processed by arch-all builders
> (provided you use -indep targets), so arch-any builds won't even feel
> that overhead, right?

Yes except that this is ot because --inplace work that the result of python=
 setup.py build are identical.

it is possible to  forget a module referenced by another module in the setu=
p.py.
It workd with --inplace but it does not work for real after build ans insta=
llation.

Cheers

Fred


I could be wrong though.