Re: help2man usage with pybuild / debhelper packaging workflow
On Sat, Jun 4, 2016 at 8:05 PM, Ghislain Vaillant wrote: > I like this approach. Any example you may have in mind? Apparently onionbalance uses sphinxcontrib-autoprogram. I plan to figure out python3-sphinx-argparse at some point for check-all-the-things. Another really useful thing to have is automatic bash completion based on the objects used for --help output. I use python3-argcomplete in check-all-the-things for that (see git master). -- bye, pabs https://wiki.debian.org/PaulWise
Re: help2man usage with pybuild / debhelper packaging workflow
On 04/06/16 05:25, Paul Wise wrote: On Sat, Jun 4, 2016 at 12:30 AM, Christian Seiler wrote: Well, you could add a custom target to debian/rules that calls help2man for all these scripts - so that you as a maintainer can refresh the manpages every now and then. (And store them in debian/ in the packaging.) That way, you don't break cross builds (manpages are pre-generated), but still automate it to a large extent. I don't think it is ever appropriate to store pre-generated files in source packages, neither in the upstream tarball nor in the Debian tarball (except for autotools cruft or VCS metadata through autorevision). For Python stuff, it is generally arch all and never needs to be cross-built so help2man is fine. That is my case, indeed. In any case, using something like sphinx and sphinxcontrib-autoprogram or python3-sphinx-argparse plus manual page source in Markdown or reStructuredText format is a better way to go since you get a nice format to write in and automatically sync your --help output with the manual page. I like this approach. Any example you may have in mind? Cheers, Ghis
Re: help2man usage with pybuild / debhelper packaging workflow
On Sat, Jun 4, 2016 at 12:30 AM, Christian Seiler wrote: > Well, you could add a custom target to debian/rules that calls > help2man for all these scripts - so that you as a maintainer > can refresh the manpages every now and then. (And store them > in debian/ in the packaging.) That way, you don't break cross > builds (manpages are pre-generated), but still automate it to > a large extent. I don't think it is ever appropriate to store pre-generated files in source packages, neither in the upstream tarball nor in the Debian tarball (except for autotools cruft or VCS metadata through autorevision). For Python stuff, it is generally arch all and never needs to be cross-built so help2man is fine. In any case, using something like sphinx and sphinxcontrib-autoprogram or python3-sphinx-argparse plus manual page source in Markdown or reStructuredText format is a better way to go since you get a nice format to write in and automatically sync your --help output with the manual page. -- bye, pabs https://wiki.debian.org/PaulWise
Re: help2man usage with pybuild / debhelper packaging workflow
On 03/06/16 17:59, Wookey wrote: On 2016-06-03 18:30 +0200, Christian Seiler wrote: On 06/03/2016 06:25 PM, Ghislain Vaillant wrote: And I don't mind for a handful of scripts. But what if you have 20 or 30? Well, you could add a custom target to debian/rules that calls help2man for all these scripts - so that you as a maintainer can refresh the manpages every now and then. (And store them in debian/ in the packaging.) That way, you don't break cross builds (manpages are pre-generated), but still automate it to a large extent. Yep, that's a reasonable plan. Ack. Missing man pages is better than things that gratuitously won't cross-build. So it is clearly a no-no. I guess the wiki page is here to give a starting point to write manpages, not automate the process of generating them. Just copying the help into a man page is mostly makework to shut lintian up. They are often very poor manpages. If the help is there already or upstream documentation is some other format (e.g. html), then if you _really_ can't be bothered making man pages, just leave it as upstream supplied. Using help2man is a worse 'solution' than doing nothing. In this case, should I leave the lintian warning on, or override it with a comment explaining why? Ghis
Re: help2man usage with pybuild / debhelper packaging workflow
On 06/03/2016 06:25 PM, Ghislain Vaillant wrote: > On 03/06/16 17:10, Wookey wrote: >> On 2016-06-03 16:43 +0100, Ghislain Vaillant wrote: >>> Dear all, >>> >>> Are there any successful examples of integration of help2man with a >>> pybuild / debhelper workflow for an arbitrary number of scripts? >> >> help2man breaks cross-building so is best avoided if you can. >> Please just write a man page. > > Yes, it is mentioned here [1]. > > [1] https://wiki.debian.org/ManPage/help2man > > And I don't mind for a handful of scripts. But what if you have 20 or > 30? Well, you could add a custom target to debian/rules that calls help2man for all these scripts - so that you as a maintainer can refresh the manpages every now and then. (And store them in debian/ in the packaging.) That way, you don't break cross builds (manpages are pre-generated), but still automate it to a large extent. Regards, Christian
Re: help2man usage with pybuild / debhelper packaging workflow
On 03/06/16 17:10, Wookey wrote: On 2016-06-03 16:43 +0100, Ghislain Vaillant wrote: Dear all, Are there any successful examples of integration of help2man with a pybuild / debhelper workflow for an arbitrary number of scripts? help2man breaks cross-building so is best avoided if you can. Please just write a man page. Yes, it is mentioned here [1]. [1] https://wiki.debian.org/ManPage/help2man And I don't mind for a handful of scripts. But what if you have 20 or 30? Ghis
help2man usage with pybuild / debhelper packaging workflow
Dear all, Are there any successful examples of integration of help2man with a pybuild / debhelper workflow for an arbitrary number of scripts? The only close example I could find was the stdeb package, but I am dealing with many more scripts and I cannot afford to list them all individually by hand. Best regards, Ghis
