生成python CLI手册页

Question

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

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

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

我发现有趣的一件事是在这个链接上:使用optparse和distutils创建手册页

Answer 1

在Python中生成文档的常用方法是使用Sphinx.例如,这就是官方Python文档中使用的内容.一旦设置了Sphinx文档项目(参见 本教程),就可以通过Sphinx文档文件生成手册页make man.你也应该改变配置中conf.py产生适当的输出.

(值得注意的是,虽然Sphinx是用Python编写文档的常用工具,但这并不意味着它是生成手册页的常用工具.使用你想要的!)

Answer 2

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

这是不是为正确记录您的项目（与狮身人面像或什么都这样，你选择）的替代品。但它对 Python 程序员有一些直接的好处：

• 您不必学习man语法。
• 您不必学习rst语法（无论如何，总有一天您应该学习它......）

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

• 您只需将一个文件添加到您的构建配置中，就会为您创建一个手册页！

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

请注意，这是现在的一部分拉入请求，以在标准库中添加一个手册页格式。