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

Question

按照(希望)常见的做法，我在单独的scripts目录中有一个Python包，其中包括几个模块和一个可执行脚本，如下所示。

除了optparse提供的自动生成的帮助之外，脚本的文档与包文档一起放在Sphinx子目录中。我想:

1. 从现有的文档
为脚本生成手册页
2. 在发行版
中包含手册页

我可以很容易地用Sphinx, man_pages设置和sphinx-build -b man来实现#1。因此，我可以调用python setup.py build_sphinx -b man并在build/sphinx/man目录中生成手册页。

现在我希望能够将生成的手册页包含在发行版tarball中，以便GNU/Linux打包器可以找到它并将其安装到适当的位置。像package_data这样的各种选项似乎在这里不起作用，因为手册页在Sphinx生成之前不存在。这也适用于i18n文件(.mo与.po文件)。

在MANIFEST.in中包含不属于源代码的文件似乎是不对的。将生成的文件提交到源存储库的可能性看起来是一件可怕的事情，我希望避免它。

应该有一种——最好只有一种——明显的方法来做这件事。

Answer 1

要在您的发行版中添加静态手册页，您可以在MANIFEST文件中添加它们。

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

其中man_pages是包含生成的手册页副本的目录。

参见:http://linuxmanpages.com/man1/man.1.php

Answer 2

我以前看到的做法是为文档提供一个构建目标，并在README文件中明确说明文档包含手册页，并且可以通过运行该构建目标来构建。然后，包维护者构建你的文档，并在包创建过程中打包它们。

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

Answer 3

我会让setup.py在调用distutils.core.setup之前生成手册页。记住，setup.py在一个层次上是python代码。您需要测试并确保即使没有安装sphinx(除非您需要sphinx)，它也能正常工作。因此，如果手册页已经存在并且sphinx不可用，也不要失败。这样，在没有sphinx的情况下解压缩您的源代码发行版的人仍然可以运行setup.py build和其他目标。

另一种选择是签入手册页，但和您一样，我觉得这很难看。

Answer 4

这个问题值得一个更好的答案，不仅仅是因为这个问题已经困扰我一段时间了。这是我的实现。

• 从我的github项目下载build_manpage.py(这里是build_manpage的链接)

• 保存到可以导入到setup.py

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

现在你可以这样调用setup.py:

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