python - 生成 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 文档项目（请参阅 本教程），您可以通过make man. 您还应该更改配置以产生适当的输出conf.py。

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

Answer 2

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

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

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

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

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

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

请注意，这现在是在标准库中添加联机帮助页格式化程序的拉取请求的一部分。

Answer 3

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