Path: csiph.com!news.mixmin.net!aioe.org!bofh.it!news.nic.it!robomod
From: Ghislain Vaillant <ghisvail@gmail.com>
Newsgroups: linux.debian.maint.python
Subject: Re: building manpages via setup.py
Date: Wed, 02 Aug 2017 11:30:01 +0200
Message-ID: <u9Y8x-83f-13@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>
Old-Return-Path: <ghisvail@gmail.com>
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-GB
Content-Transfer-Encoding: 7bit
Approved: robomod@news.nic.it
Lines: 62
Organization: linux.* mail to news gateway
Sender: robomod@news.nic.it
Xref: csiph.com linux.debian.maint.python:9675



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.