Re: Debian-way мануалы для python-скриптов
On Mon, May 11, 2020 at 11:03:40AM +0300, Victor Wagner wrote: > В Sun, 10 May 2020 23:31:41 +0300 > Peter Pentchev пишет: > > > On Thu, Apr 23, 2020 at 12:15:52PM +0300, Victor Wagner wrote: > > > В Thu, 23 Apr 2020 11:51:48 +0400 > > > a.v.korot...@gmail.com пишет: > > > > > > > On Thu, 23 Apr 2020 09:34:37 +0300 > > > > Victor Wagner wrote: > > > > > > > > VW> dh_python из коробки поддерживает систему документирования > > > > VW> sphynx, Но я заглянул в её описание и понял, что ничего не > > > > VW> понял. Она ориентирована в первую очередь на написание > > > > VW> документации к библиотека, для программистов, а не на > > > > VW> man-страницы, для пользователей. > > > > > > > > В сторону Asciidoc гляньте (сам не пробовал). > > > > > > Дело не в том, какой язык разметки использовать. > > > > > > В конце концов писал я 20 лет маны непосредственно на *roff. > > [snip] > > > > BTW пробовали когда-то -mdoc? Мне всегда казалось, что лучше > > использовать семантичних макросов, а не типографских. > > В -man более чем достаточно семантических макросов. > Да, в некоторых сообществах принят такой стиль, когда используют > физическую разметку, например в Tcl это очень любят. Но это именно > заморочки конкретных сообществ. Ну, мне -mdoc более чем 20 лет назад во FreeBSD научили :) > в> > Если же это правило писать вручную через override_dh_auto_install, > > > то придется потом debian/rules хранить в git, а не перегенерировать > > > каждый раз с помощью py2dsp из пакета pypi2deb. > > > > Если Вы уже используете debhelper, тогда у Вас dh_installman > > вызывается автоматично, так что опишите something.1 и another.1 > > в debian/manpages, он их поставит. Конечно, если самие *.1 > > Это все, конечно хорошо, но как объяснить питноовскому setuptools > что по команде setup.py sdist их надо в orig.tar.gz положить? setuptools.setup( ..., data_files=[ ("/usr/share/man/man1", ["progname.1", "another.1"]), ], ..., ) Не то? Ну, не всегда очень хорошо работает с wheels :( > > не в upstream source, debian/manpages может содержать и пут > > В том-то и дело, что мне хочется сформировать такой upstream source, > который был бы весь из себя pythonway, настолько что я бы мог не > заботиться о ручном написании содержимого директории debian, > зная что py2dsc все сделает правильно. > > Я не хочу хранить debian/* в version control, хочу их каждый раз > воссоздавать автоматически Понятно; извините, мне следовало бы сразу понять - Вы говорили о том. Всего лучшего, Петр -- Peter Pentchev r...@ringlet.net r...@debian.org p...@storpool.com PGP key:http://people.FreeBSD.org/~roam/roam.key.asc Key fingerprint 2EE7 A7A5 17FC 124C F115 C354 651E EFB0 2527 DF13 signature.asc Description: PGP signature
Re: Debian-way мануалы для python-скриптов
В Sun, 10 May 2020 23:31:41 +0300 Peter Pentchev пишет: > On Thu, Apr 23, 2020 at 12:15:52PM +0300, Victor Wagner wrote: > > В Thu, 23 Apr 2020 11:51:48 +0400 > > a.v.korot...@gmail.com пишет: > > > > > On Thu, 23 Apr 2020 09:34:37 +0300 > > > Victor Wagner wrote: > > > > > > VW> dh_python из коробки поддерживает систему документирования > > > VW> sphynx, Но я заглянул в её описание и понял, что ничего не > > > VW> понял. Она ориентирована в первую очередь на написание > > > VW> документации к библиотека, для программистов, а не на > > > VW> man-страницы, для пользователей. > > > > > > В сторону Asciidoc гляньте (сам не пробовал). > > > > Дело не в том, какой язык разметки использовать. > > > > В конце концов писал я 20 лет маны непосредственно на *roff. > [snip] > > BTW пробовали когда-то -mdoc? Мне всегда казалось, что лучше > использовать семантичних макросов, а не типографских. В -man более чем достаточно семантических макросов. Да, в некоторых сообществах принят такой стиль, когда используют физическую разметку, например в Tcl это очень любят. Но это именно заморочки конкретных сообществ. в> > Если же это правило писать вручную через override_dh_auto_install, > > то придется потом debian/rules хранить в git, а не перегенерировать > > каждый раз с помощью py2dsp из пакета pypi2deb. > > Если Вы уже используете debhelper, тогда у Вас dh_installman > вызывается автоматично, так что опишите something.1 и another.1 > в debian/manpages, он их поставит. Конечно, если самие *.1 Это все, конечно хорошо, но как объяснить питноовскому setuptools что по команде setup.py sdist их надо в orig.tar.gz положить? > не в upstream source, debian/manpages может содержать и пут В том-то и дело, что мне хочется сформировать такой upstream source, который был бы весь из себя pythonway, настолько что я бы мог не заботиться о ручном написании содержимого директории debian, зная что py2dsc все сделает правильно. Я не хочу хранить debian/* в version control, хочу их каждый раз воссоздавать автоматически --
Re: Debian-way мануалы для python-скриптов
On Thu, Apr 23, 2020 at 12:15:52PM +0300, Victor Wagner wrote: > В Thu, 23 Apr 2020 11:51:48 +0400 > a.v.korot...@gmail.com пишет: > > > On Thu, 23 Apr 2020 09:34:37 +0300 > > Victor Wagner wrote: > > > > VW> dh_python из коробки поддерживает систему документирования sphynx, > > VW> Но я заглянул в её описание и понял, что ничего не понял. Она > > VW> ориентирована в первую очередь на написание документации к > > VW> библиотека, для программистов, а не на man-страницы, для > > VW> пользователей. > > > > В сторону Asciidoc гляньте (сам не пробовал). > > Дело не в том, какой язык разметки использовать. > > В конце концов писал я 20 лет маны непосредственно на *roff. [snip] BTW пробовали когда-то -mdoc? Мне всегда казалось, что лучше использовать семантичних макросов, а не типографских. Пример: https://gitlab.com/confget/confget/-/blob/master/confget.1 > Если же это правило писать вручную через override_dh_auto_install, то > придется потом debian/rules хранить в git, а не перегенерировать каждый > раз с помощью py2dsp из пакета pypi2deb. Если Вы уже используете debhelper, тогда у Вас dh_installman вызывается автоматично, так что опишите something.1 и another.1 в debian/manpages, он их поставит. Конечно, если самие *.1 не в upstream source, debian/manpages может содержать и пути внутри debian/*, как в https://sources.debian.org/src/mktorrent/1.1-2/debian/manpages/ Всего лучшего, Петр -- Peter Pentchev r...@ringlet.net r...@debian.org p...@storpool.com PGP key:http://people.FreeBSD.org/~roam/roam.key.asc Key fingerprint 2EE7 A7A5 17FC 124C F115 C354 651E EFB0 2527 DF13 signature.asc Description: PGP signature
Re: Debian-way мануалы для python-скриптов
В Thu, 23 Apr 2020 11:51:48 +0400 a.v.korot...@gmail.com пишет: > On Thu, 23 Apr 2020 09:34:37 +0300 > Victor Wagner wrote: > > VW> dh_python из коробки поддерживает систему документирования sphynx, > VW> Но я заглянул в её описание и понял, что ничего не понял. Она > VW> ориентирована в первую очередь на написание документации к > VW> библиотека, для программистов, а не на man-страницы, для > VW> пользователей. > > В сторону Asciidoc гляньте (сам не пробовал). Дело не в том, какой язык разметки использовать. В конце концов писал я 20 лет маны непосредственно на *roff. Вопрос в интеграции конвертера этого языка с дебиановскими средствами пакетирования python-скриптов и самим setuptools. Нужно с одной стороны обеспечить, чтобы setup.py не забыл положить исходник документации в tarball исходников по команде sdist, с другой, чтобы в debian/rules отработало правило, которое уже преобразованные в *roff man-страницы установило в /usr/share/man/man1 и /usr/share/man/ru/man1. Если же это правило писать вручную через override_dh_auto_install, то придется потом debian/rules хранить в git, а не перегенерировать каждый раз с помощью py2dsp из пакета pypi2deb. У asciidoc я никаких средств для этого не увидел. У sphynx это есть, но непонятно как в spynx c минимальными трудозатратами сделать правильные man-страницы, со стандартным для man набором разделов. --
Re: Debian-way мануалы для python-скриптов
On Thu, 23 Apr 2020 09:34:37 +0300 Victor Wagner wrote: VW> dh_python из коробки поддерживает систему документирования sphynx, VW> Но я заглянул в её описание и понял, что ничего не понял. Она VW> ориентирована в первую очередь на написание документации к VW> библиотека, для программистов, а не на man-страницы, для VW> пользователей. В сторону Asciidoc гляньте (сам не пробовал).
Debian-way мануалы для python-скриптов
Коллеги, Может быть кто поделится опытом - как правильно писать man-ы для скриптов на питоне. dh_python из коробки поддерживает систему документирования sphynx, Но я заглянул в её описание и понял, что ничего не понял. Она ориентирована в первую очередь на написание документации к библиотека, для программистов, а не на man-страницы, для пользователей. А у меня фактически чистый командно-строчный скрипт, хотя и организован по питоновским правилам - набор модулей и setup.py на setuptools, который генерирует запускалку. И lintian, естественно, ворчит что вот есть исполняемый файл в /usr/bin а man-страницы к нему нет. Ну то есть понятно, что можно после генерации пакетировочных файлов прописать туда override_dh_install и подложить написанную руками на *roff страничку, но хочется как-то поэстетичнее, чтобы потом поддерживать легче было. Писать же исходник на *roff, markdown или rst - как-то все равно. Дополнительная призовая игра - а чтобы многоязычные (русского и английского для начала хватит) маны? --