Cannot get `setup.py build` to build man pages

[rrthomas]

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 and setup.cfg code from the docs, and when I run setup.py build_py the man pages are built, but when I run setup.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!

[rrthomas]

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

[rrthomas]

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.

[praiskup]

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.

[rrthomas]

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!

[praiskup]

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?

[rrthomas]

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.

[praiskup]

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.

[praiskup]

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.

[rrthomas]

@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.

[praiskup]

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.

[rrthomas]

Happy to see what you come up with, even if my reaction is just "oh no, sorry, I also need this other help2man feature…"!

[ssbarnea]

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.

[rrthomas]

@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

[ssbarnea]

@rrthomas The offer is for @praiskup but to answer your question, there are two types of challanges:

• projects that were doing shady things in setup.py and doing staff that was known for more than a decade as not being safe. (installing man page or file in non-package location is such thing).
• human factor - maintainers are busy and afraid of new, as new often means new source of problems.

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).

[rrthomas]

@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).

[praiskup]

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!

[rrthomas]

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!

[rrthomas]

I managed to get most of my setup.cfg moved into pyproject.toml. I will file an issue about the remaining bits.

[rrthomas]

I think this issue can be closed now; I have submitted a PR to add --include support.

[praiskup]

Thank you, closing then. See #80 for more info.