Question

遵循（希望）常见做法，我有一个Python包，其中包含多个模块和一个可执行脚本，位于单独的scripts目录中，如here所示。

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

从现有文档
在分发中包含手册页

我可以轻松地使用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 vs .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

我会在调用distutils.core.setup之前导致setup.py生成手册页。请记住，一个级别的setup.py是python代码。您想要测试并确保即使未安装sphinx也能正常工作（除非您需要sphinx）。因此，如果手册页已经存在且sphinx不可用，请不要失败。这样，在没有sphinx的情况下解压缩源代码的人仍然可以运行setup.py构建和其他目标。

另一种选择是检查手册页，但是和你一样，我觉得很难看。

Answer 3

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

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

Answer 4

这个问题应该得到更好的答案，而不仅仅是因为这个问题困扰了我一段时间。所以这是我的实现。

从我的github项目（此处为a link to build_manpage）

build_manpage.py

将其保存在您可以将其导入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

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

4 个答案: