How to generate man pages at build time ?

[gtristan]

Hi,

I realize from reading your README that you may not consider this a bug, this is fine I'm not arguing this, but I need some help to figure out how to do what the README recommends not doing, I've spent an entire day swimming in setuptools/distutils code and still have not resolved this.

Currently, I have a horrible work around which is to generate the man pages in tree and commit the result to my source tree, which means I need to manually re-run and re-commit man pages whenever my frontend CLI commands and/or documentation changes.

After this, I am able to specify with setup() 'data_files' that the man pages go into ${prefix}/share/man/man1, this part works very well because:

• It works regardless if you install into /usr, /usr/local or for a single user in ~/.local
• The man pages are a part of the package, so they will be installed and uninstalled with the package
• It remains encapsulated in setuptools and is a part of the distribution, so anyone who might want to create a distro package from our upstream source base should not have a problem jumping through any extra hoops to get the man pages installed.
• Even on non-unixy platforms (which we dont currently support), this should not be an issue because:
  • Again most importantly the man pages are a part of the logical package, so if they are installed they should be well tracked regardless of packaging mechanism and installed/uninstalled with the package
  • If the non-unixy platform does not provide a man program to read the man pages in some standard location, then those man pages will not cause the user any harm.

My related setup.py is here, and I tried to follow this blog post for the purpose of ensuring the man pages are automatically built in the build stage, but I can't seem to wrap my head around this or get it to work.

From what I understand, I should be able to:

• Override build_py with my own command by specifying cmdclass in setup()
• Add the click_man package to install_requires or such, which will ensure click_man is available to import when the overridden build_py "command" is run
• Import the distutils "Command" from click_man.man_pages directly inside the overridden build_py function, when click_man is finally guaranteed to exist
• Run the click_man command from that function as a post-build step

I am sadly not able to achieve the above, or have not understood the correct way to do this.

Any help here would be really greatly appreciated, thanks.