Closed rrthomas closed 1 year ago
Example code: see https://github.com/rrthomas/rpl/tree/tox
With this branch checked out:
$ python setup.py build_py
running build_py
running build_manpages
generating rpl.1
$ python setup.py build
running build
running build_scripts
copying and adjusting rpl -> build/scripts-3.10
I see that build
is not a setuptools command, but a distutils command. If I override that in the same way, then I can get code to be run by python setup.py build
.
Thank you for the report @rrthomas! I think I fail to reproduce or understand the issue though.
We are not overriding with distutils methods, but setuptools. But otherwise this is exactly what we are doing in this project.
$ python setup.py build
running build
running build_py
running build_manpages
generating man/argparse-manpage.1
file build_manpage.py (for module build_manpage) not found
file build_manpage.py (for module build_manpage) not found
The warning is to be fixed in #68.
I was using distutils's build
method because if I override setuptools's build_py
then python setup.py build
does not build the man page. But if I understand correctly, python setup.py build
is deprecated anyway, so I should be doing something else. I will look at your example, thanks!
For the record, the API for this was simplified in v4; the setuptools' "parent" commands are now optional and you can just do:
from build_manpages import get_build_py_cmd, get_install_cmd
setup(
...
cmdclass={
'install': get_install_cmd(),
'build_py': get_build_py_cmd(),
},
...
... then setuptools
are used with a fallback to distutils when necessary. WDYT?
Thanks, this looks good. In my case, I want to use help2man
to build the man page, not argparse-manpage
, so I need to override, or possibly not use get_build_py_cmd()
, and I'm not sure what to do in this case.
Ffeedback why help2man
is better would be welcome, I'd like to make argparse-manpage versatile enough.
But anyway, as long as your override for the build command generates the manual page in an appropriate place, I think everything should work fine. But I'm afraid you'll have to do all the configuration in setup.cfg or alike.
I'd like to make argparse-manpage versatile enough.
Alternatively., considering help2man
is more useful in some circumstances, we could possibly create
a specific option for this (provide native help2man support).
This is how build_manpages
generates the manual page.
@praiskup it would of course be fantastic if argparse-manpage
could replace help2man
. The feature of help2man
that I miss most is the ability to add the contents of an include file to a generated man page. There's some very simply templating that occurs; see the section "INCLUDE FILES" of help2man(1).
But as you suggest later, it might be simpler to add native help2man support rather than try to replicate its functionality.
This include-files concept is indeed interesting - and seems relatively easy to implement. I'm +1, even though it motivates the user to think about the manual page "separately" from the --help
output; and the man page then contains more complete info. Similar to https://github.com/praiskup/argparse-manpage/issues/7.
I'm thinking about using the help2man
script, but that is Perl. So we'd have to execute help2man, and let the tool execute the script with ArgumentParser Python object. And this wouldn't be easy - we might not know how to call the script. So the former option with --opt-include
seems easier.
Happy to see what you come up with, even if my reaction is just "oh no, sorry, I also need this other help2man feature…"!
TBH, I would prioritize removal of setup.py and setup.cfg as part of https://peps.python.org/pep-0621/ -- probably I could give a hand as I already did more than 20 such migrations.
@ssbarnea I wasn't clear whether that was an offer to me; in any case, having wrestled with two projects that I have been unable to remove setup.py
from (let alone migrate to pyproject.toml
), I would love some help moving into the future. The projects in question are https://github.com/rrthomas/rpl and https://code.launchpad.net/~caffeine-developers/caffeine/main
@rrthomas The offer is for @praiskup but to answer your question, there are two types of challanges:
TBW, I even created a topic on github for projects already moved https://github.com/topics/pep-621 (many others already did but did not add the topic).
@ssbarnea thanks for the pointers. Obviously I'm not too worried about migrating, as I already tried it. In one of the packages I mentioned, rpl
, the problem is that I couldn't work out how to use argparse-manpage
without having setup.py
. In the other project, caffeine
, my setup.py
is mainly there to handle gettext translations (I tried using Babel, but couldn't work out how to use it), and some files that are installed in locations that Python does not seem to know about (specifically, /etc/xdg/autostart
).
TBH, I would prioritize removal of setup.py and setup.cfg as part of https://peps.python.org/pep-0621/ -- probably I could give a hand as I already did more than 20 such migrations.
PR would be welcome, thanks!
I managed to avoid both distutils
and direct execution of python setup.py
with https://github.com/rrthomas/rpl/commit/feab231.
I had to include build_manpages
as a submodule for this, following the instructions in the argparse-manpage
docs; this is a shame, as I then had to ensure pytest
didn't try to run the included tests, which fail.
I still don't really understand how the pieces fit together, and I now have a pyproject.toml
as well as setup.cfg
and setup.py
, which is a shame, as the promised improvements in Python packaging seem instead to be making things more complicated. The only real win I have here is that my code will continue to work with Python 3.12 when distutils
goes away. (In the mean time I have to sit through even more deprecation warnings from the pytest-executable
plugin!).
Since I am converting other projects to Python that have similar problems (i.e. they use help2man
to generate man pages with included files), I would love to see this feature added to argparse-manpage
!
I managed to get most of my setup.cfg
moved into pyproject.toml
. I will file an issue about the remaining bits.
I think this issue can be closed now; I have submitted a PR to add --include
support.
Thank you, closing then. See #80 for more info.
In the documentation it says: "Also, if you used get_build_py helper, setup.py build then transitively builds the manual pages."
However, this doesn't work for me. I have used the
setup.py
andsetup.cfg
code from the docs, and when I runsetup.py build_py
the man pages are built, but when I runsetup.py build
they are not.I'm using Python 3.10 and setuptools 59.6.0 (from Ubuntu 22.04), and argparse-manpage 3 from PyPI.
Thanks for argparse-manpage, it's the Right Way To Do It!