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

Groups > linux.debian.maint.python > #9675

Re: building manpages via setup.py

Show key headers only | View raw

On 02/08/17 09:55, PICCA Frederic-Emmanuel wrote:
>> PYTHONPATH=. sphinx-build -N -b html <docs_dir> <build_dir>
> 
>> One can also use the sphinx-generated Makefile if available:
> 
>> PYTHONPATH=$(CURDIR) $(MAKE) -C <docs_dir> html
> 
>> Both are simple one-liners and do not rely on pybuild.
> 
> Yes it works but this is fragile since the organisation of the module can change in the sources.

First, that's very speculative. Second, that's upstream's problem.

I have not seen many upstream projects playing with the layout of their 
modules from one version to the next. If that's the case, then there are 
worst things to be worried about (API breakage for instance) than the docs.

> at least the .pybuild directory is under the responsability of pybuild and we should use pybuild instead of relying
> on the maintainer snipset. (typo error, change during the time.)

The upstream Makefile and conf.py are likely generated by Sphinx itself 
via sphinx-quickstart. Did your upstream tinker with them that much that 
they cannot be trusted?

> It would be nice if the doc generation in python shold be standardize.

Some upstream do use a build_sphinx command, but it is far from common 
and it does not solve the extension module problem.

>> If it does not cost much to build the extension inplace, then the
>> simplest option is to prefix one of these calls above with:
> 
>> python3 setup.py build_ext --inplace
> 
> when you have multiple verison of the interpreter you prefer to avoid --inplace.

Why? All you need is *one* occurrence of the extension modules somewhere 
in the PYTHONPATH in order to generate the docs. Chances are that's how 
upstream generates them.

I fail to picture how this is an issue in practice considering your 
build override will run the isolated pybuilds first and the sphinx call 
last.

>> If the cost is prohibitive, which arguably applies to a very limited set
>> of packages (yours included) then you would use pybuild for that, as
>> Piotr kindly suggested.
> 
> Yes it depends olsa of the arch. Some are really slow....

That's unfortunate, indeed.

>> Considering the rarity of this use case though, I wonder whether it is
>> worth adding a separate section to the style guide.
> 
> Found a total of 643 reverse build-depend(s) for python-all-dev.
> 
> not that small

How is the ratio over all the Python packages? I suspect very small.

Back to linux.debian.maint.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-01 16:50 +0200
  Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-01 17:00 +0200
    RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-01 17:50 +0200
  Re: building manpages via setup.py Piotr Ożarowski <piotr@debian.org> - 2017-08-01 17:40 +0200
    RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 09:20 +0200
      Re: building manpages via setup.py Piotr Ożarowski <piotr@debian.org> - 2017-08-02 09:30 +0200
        Re: building manpages via setup.py Piotr Ożarowski <piotr@debian.org> - 2017-08-02 09:50 +0200
          Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 09:50 +0200
            Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 10:20 +0200
              RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 10:40 +0200
                Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 10:40 +0200
                RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 11:20 +0200
                Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 11:30 +0200
                RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 12:10 +0200
                Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 12:50 +0200
                RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 14:30 +0200
            RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 10:30 +0200
        RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 09:50 +0200
        RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-03 12:20 +0200
          RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-03 15:50 +0200
            RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-03 16:20 +0200

csiph-web