Python command line program: generate man page from existing documentation and include in the distribution

Question

Following an (hopefully) common practice, I have a Python package that includes several modules and an executable script in a separate scripts directory, as can be seen here.

The documentation for the script, apart from the auto-generated help given by optparse, is together with the package documentation in a Sphinx subdirectory. I am trying to:

1. generate the man page for the script from the existing documentation
2. include the man page in the distribution

I can easily do #1 with Sphinx, the man_pages setting and sphinx-build -b man. So I can call python setup.py build_sphinx -b man and have the man page generated in the build/sphinx/man directory.

Now I would like to be able to have the generated man page included in the distribution tarball, so GNU/Linux packagers can find it and install it to the proper location. Various options like package_data do not seem to work here because the man page is not there until it is generated by Sphinx. This could also apply to i18n files (.mo vs .po files).

Including files that are not part of the source in MANIFEST.in doesn't seem right. The possibility of commiting the generated files to the source repository looks like an awful thing to do and I would like to avoid it.

There should be one-- and preferably only one --obvious way to do it.

Answer 1

To add static man pages in you distribution, you can add them in the MANIFEST file.

recursive-include docs *.txt
recursive-include po *.po
recursive-include sample_data *
recursive-include data *.desktop *.svg *.png
include COPYING.txt
include README.txt
recursive-include man_pages

Where man_pages is the directory containing the copies of generated man pages.

See also: http://linuxmanpages.com/man1/man.1.php

Answer 2

I would cause setup.py to generate the man pages probably before calling distutils.core.setup. Remember that setup.py at one level is python code. You want to test and make sure that it works even if sphinx is not installed (unless you require sphinx). So, if the man pages already exist and sphinx is not available do not fail. That way someone who unpacks your source distribution without sphinx can still run setup.py build and other targets.

The other option is to check in the man pages, but like you, I find that ugly.