生成python CLI手册页

Question

我正在开发一个python CLI工具（在python2.6中使用optparse，但希望很快切换到python2.7），我即将编写手册页。我有一些生成动态手册页的经验：

• 创建一个专用方法，在pod format中组合一个字符串并将其写入文件
• 执行pod2man命令以生成groff格式的数据以传递给man命令

我还想生成与手册页具有相同内容的wiki页面（使用pod我可以通过pod2html生成html，并且可能很容易将html翻译成wiki格式）。有人对如何做到这一点有更好的想法/流程吗？

我发现有趣的一件事是在这个链接：Creating Man Pages Using optparse and distutils

Answer 1

在Python中生成文档的常用方法是使用Sphinx。例如，这就是官方Python文档中使用的内容。一旦设置了Sphinx文档项目（请参阅this tutorial），您就可以通过make man从Sphinx文档文件生成手册页。您还应该在alter the configuration中使用conf.py来产生适当的输出。

（值得注意的是，虽然Sphinx是用Python编写文档的常用工具，但这并不意味着它是生成手册页的常用工具。使用你想要的！）

Answer 2

虽然sphinx是一个非常棒的文档系统，但它非常复杂且难以掌握。如果你需要一个爆炸解决方案，我建议你看看我的项目build_manpage.py。

它不能替代正确记录您的项目（使用sphinx或您选择的方式）。但它对Python程序员有一些直接的好处：

• 您不必学习man语法。
• 你不必学习rst语法（从来没有，你应该有一天学习它......）
• 您不需要在外部文件（在man，rst或任何其他转换系统中）维护optparse \ argparse和手册页格式。
• 您只需在构建配置中添加一个文件，就会为您创建一个手册页！

如果你想使用一个更复杂的系统，有很多花里胡哨，sphinx允许你将rst格式化的页面转换为手册页。最近一个年轻的项目，对我的解析器采取了类似的方法，扫描你的ArgumentParser生成一个rst格式的页面，使用sphinx指令（这样你不需要自己编写。（相比之下，我的扫描仪直接生成一个手册页） ）。

请注意，现在这是pull request到add a manpage formatter in the standard library的一部分。

Answer 3

如果您使用click，您可以使用click-man。它可以从点击应用程序生成手册页。