python - 如何使用 sphinx 为 1 文件 python 项目(脚本，无模块)生成文档？

Question

我有一个Python项目，它存储在一个文件中，它是一个命令行工具。

我已经成功使用 sphinx 生成了文档，但如何确定我的文件是脚本而不是模块？

Answer 1

有多个选项可用于记录用 Python 编写的命令行工具:

• 命令直接显示帮助字符串
• README.rst 用 reStructuredText 编写并通过 rst2html 转换为 html
• Sphinx 文档

(我不声称，这个列表是完整的)

从命令行打印帮助字符串

这是迄今为止最容易访问的文档形式，因为安装该程序的每个人都可以显示它。

我强烈建议使用 docopt 来解析命令行，因为它为您带来最好的效果 - 在源代码中包含文档字符串(作为模块文档字符串)，同时在命令行上。

你可以在SO https://stackoverflow.com/a/23304876/346478中看到我的帖子或者在这里您可以看到项目本身的示例:

"""Usage:
quick_example.py tcp <host> <port> [--timeout=<seconds>]
quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
quick_example.py -h | --help | --version

"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='0.1.1rc')
    print(arguments)

从命令行运行时:

$ python quick_example.py -h
Usage:
  quick_example.py tcp <host> <port> [--timeout=<seconds>]
  quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
  quick_example.py -h | --help | --version

还有其他参数解析器，例如 plac 或 argparse。我个人最喜欢docopt。

README.rst 用 reStructuredText 编写并通过 rst2html 转换为 html

编写 README.rst 非常简单，并且有一个优点，即在 github 和 bitbucket 上，您可以在项目自动呈现时获得非常可读的介绍。

它也比 Sphinx 项目简单得多，您不必使用多个文件，只需一个即可。

安装 docutils 时:

$ pip install docutils

你会得到一堆命令，它们可以让你将 README.rst 转换成不错的东西。我在这组命令中使用的唯一命令是 rst2html(在 Windows 上它是 rst2html.py，你必须玩一点才能让它工作，但它绝对值得) )。

为 README.rst 创建 html:

$ rst2html README.rst README.html

我是在我的 vim 编辑器中完成的，它变得更加简单 :!rst2html % %.html 生成 README.rst.html 文件。

Sphinx 文档

我认为 Sphinx 是 reStructuredText 的出色扩展，并用它编写了几本技术小册子 - 它提供了出色的交叉引用语法，我喜欢它。

但对于命令行工具，我认为它太过分了。

有关如何使用 Sphinx 的说明，请参阅他们的精彩文档。

结论

Sphinx 很棒，但对于命令行工具来说似乎有点过分了。

reStructuredText README.rst 应该是任何 Python 项目的必备部分，无论大小如何，当您忘记项目的所有内容时，将您认为方便的所有内容都放在那里。

另一方面，我以 html 形式向用户提供了一组页面，但我不确定他们真正阅读这些页面的频率。人都是懒惰的。

命令行上的帮助选项文档似乎最适合我。目前，您需要帮助(在命令行上输入)，您就可以得到它。借助像 docopt 这样的包，它可以与源代码中的文档字符串完美一致。

如果您想对用户进行投资，请教他们less(或more)命令，使用这几个热键来搜索/对于字符串，跳转到下一个匹配项 n，返回一个匹配项 N，跳转到顶部 gg 或底部 G >。 h 或 H 成为您的 friend ，q 成为您的安全漏洞。

享受命令行生活。