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

The thing that I have seen done before is to provide a build target for your docs and make it clear in the README file that the documentation includes man pages and can be built by running that build target. Package maintainers then build your docs and package them during the package creation process.

The fedora 18 rpm for hawkey, for example, builds this way. I have also seen other rpms follow the model of building documentation at the same time as the source is built, then packaging it.

Answer 3

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.

Answer 4

This question deserve a better answer, and not only because this issue has been bothering me for a while. So here is my implementation.

• Download build_manpage.py from my github project (here is a link to build_manpage)

• Save it somewhere you can import it to your setup.py

  # inside setup.py
  from setuptools import setup
  from build_manpage import BuildManPage
  
  ...
  ...
  
  setup(
  ...
  ...
  cmdclass={
  'build_manpage': BuildManPage,
  )
  

Now you can invoke setup.py like this:

$ python setup.py build_manpage --output=prog.1 --parser=yourmodule:argparser