click-man

创建click应用的手册页就像这样

python3 setup.py --command-packages=click_man.commands man_pages

→ 查看deb打包示例[链接]

功能

click-man将为您的click CLI应用中在setup.py中的console_scripts中指定的每个命令生成一个man手册页。

安装

pip3 install click-man

click-man也适用于Python 2

pip install click-man

使用示例

以下部分描述了不同使用click-man的示例。

与已安装的包一起使用

click-man提供自己的命令行工具，可以传递已安装脚本的名称

click-man commandname

其中commandname是已安装的console_script入口点的名称。

要指定man手册页的目标目录，请使用--target选项

click-man --target path/to/man/pages commandname

与setuptools一起使用

click-man提供合理的setuptools命令扩展，可以像以下这样使用

python3 setup.py --command-packages=click_man.commands man_pages

或指定man手册页的目标目录

python3 setup.py --command-packages=click_man.commands man_pages --target path/to/man/pages

使用setuptools和pip自动安装man手册页

这种安装man手册页的方法存在各种问题

(1) man手册页是UNIX的东西

Python以及pip和setuptools旨在具有平台无关性。man手册页不是：它们是UNIX的东西，这意味着setuptools不提供生成和安装man手册页的合理解决方案。我们应该考虑仅在供应商特定的打包中（例如，对于*.deb或*.rpm包）使用自动安装man手册页。

(2) man手册页与Python虚拟环境不兼容

即使在支持man手册的系统上，Python包也可以通过pip和setuptools安装到virtualenv中，而不会全局提供命令。实际上，virtualenv的一个“特性”就是可以安装包而不影响主系统。由于无法确保只有在未安装到virtualenv时才生成man手册，自动生成的man手册会污染主系统，而不会在virtualenv中保持封装。此外，由于用户可以在同一系统上的多个不同virtualenv中安装同一包的不同版本，因此无法保证全局安装的man手册会记录任何给定virtualenv中可用的版本和行为。

(3) 我们希望在动态生成man手册

首先，我们不想将man手册提交到源代码控制。我们希望动态生成它们。无论是构建还是安装时。

使用setuptools和pip，我们面临两个问题

1. 如果我们生成并安装它们在包的安装过程中，pip不知道man手册，因此无法卸载它。
2. 如果我们将它们生成到我们的构建过程中，并将其添加到您的发行版中，我们无法防止非UNIX-like操作系统上的/usr/share/man安装或从virtualenv中安装。

Debian软件包

debhelper软件包提供了一个非常方便的脚本，名为dh_installman。它会检查debian/(pkg_name.)manpages文件及其内容，这基本上是一行行列出man手册或glob的列表。

debian/tmp/manpages/*

我们覆盖了dh_installman提供的规则，提前生成我们的man手册，如下所示

override_dh_installman:
	python3 setup.py --command-packages=click_man.commands man_pages --target debian/tmp/manpages
	dh_installman -O--buildsystem=pybuild

现在我们可以使用您选择的工具构建我们的Debian软件包，例如

debuild -us -uc

在此处检查一个工作示例：[repo Debian软件包](https://github.com/timofurrer/click-man/tree/master/examples/debian_pkg)