生成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文档文件生成手册页。您还应conf.py {{1}}生成适当的输出。

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

Answer 2

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

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

• 您不必学习man语法。
• 你不必学习rst语法（从来没有，你应该有一天学习它......）

• 您不需要维护您的optparser \ argparser 和在外部文件（在man，rst或任何其他转换系统中）格式化的手册页。

• 您只需为构建配置添加一个文件，并为您创建一个手册页！

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

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

Answer 3

如果您使用的是click，则可以使用github samples。 它可以从点击应用程序生成手册页。