Python命令行程序:从现有文档生成手册页并包含在发行版中

Question

遵循(希望)常见的做法,我有一个Python包,其中包含几个模块和一个可执行脚本在一个单独的scripts目录中,如这里所示.

除了optparse提供的自动生成的帮助之外,脚本的文档与Sphinx子目录中的包文档一起使用.我在尝试着:

1. 从现有文档生成脚本的手册页
2. 包括分发中的手册页

我可以轻松地与Sphinx一起做#1,man_pages设置和sphinx-build -b man.所以我可以调用python setup.py build_sphinx -b man并在build/sphinx/man目录中生成手册页.

现在我希望能够将生成的手册页包含在分发tarball中,因此GNU/Linux包装程序可以找到它并将其安装到正确的位置.像package_data这样的各种选项似乎不起作用,因为在Sphinx生成之前,手册页不存在.这也适用于i18n文件(.movs .po文件).

包含不属于源的文件MANIFEST.in似乎不对.将生成的文件提交到源存储库的可能性看起来很糟糕,我想避免它.

应该有一个 - 最好只有一个 - 明显的方法来做到这一点.

Answer 1

我之前见过的做法是为您的文档提供构建目标，并在自述文件中明确说明文档包含手册页，并且可以通过运行该构建目标来构建。然后，包维护人员会在包创建过程中构建您的文档并打包它们。

例如，hawkey的 fedora 18 rpm就是以这种方式构建的。我还看到其他 rpm 在构建源代码的同时遵循构建文档的模型，然后将其打包。