生成python CLI手册页 [英] Generating python CLI man page

问题描述

我正在开发python CLI工具（在python2.6中使用 optparse ，但希望很快切换到python2.7），而我将要编写手册页。
我在通过以下方式生成动态手册页方面有一些经验：

I am developing a python CLI tool (using optparse in python2.6, but hope to switch soon to python2.7) and I am about to write the man page. I have some experience on generating dynamic man pages by:

• 创建一种专用方法，该方法在 pod格式并将其写入文件


• 执行 pod2man 命令以groff格式生成要传递给man命令的数据

• creating a dedicated method that composes a string in pod format and writes it to a file
• executing the pod2man command to generate data in groff format to be passed to the man command

我还想生成与手册页内容相同的Wiki页面（通过pod，我可以通过 pod2html ，并且很可能将html轻松转换为wiki格式）。
是否有人对此有更好的想法/流程？

I would also like to generate wiki pages with the same content as the man page (with pod I can generate html through pod2html, and probably the html can be easily translated into wiki format). Has someone a better idea/flow on how to do this?

我在此链接上发现了一件有趣的事情：使用optparse和distutils创建手册页

One thing I have found as interesting is on this link: Creating Man Pages Using optparse and distutils

推荐答案

在Python中生成文档的通常方法是使用狮身人面像。例如，这就是Python官方文档中使用的内容。一旦设置了Sphinx文档项目（请参阅本教程），便可以从您的Sphinx文档文件通过 make man 。您还应该在<$ c $中更改配置。 c> conf.py 来产生适当的输出。

The usual way to generate documentation in Python is to use Sphinx. For example, that's what's used in the official Python documentation. Once you have a Sphinx documentation project set up (see this tutorial), you can generate man pages from your Sphinx documentation files via make man. You should also alter the configuration in conf.py to produce appropriate output.

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

(It's worth noting that while Sphinx is the usual tool for writing documentation in Python, that doesn't mean it's the usual tool for generating man pages. Use what you want!)

这篇关于生成python CLI手册页的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！