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

时间:2014-04-29 17:39:32

标签: python python-sphinx

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

我设法用sphinx allready生成文档,但是如何确定我的文件是脚本而不是模块?

1 个答案:

答案 0 :(得分:1)

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

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

(我没有声称,此列表已完成)

从命令行打印的

帮助字符串

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

我强烈建议使用docopt来解析命令行,因为它最重要的是 - 在源代码中使用docstring(作为模块docstring)并同时在命令行中使用。

您可以在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

还有其他参数解析器,例如placargparse。就个人而言,我最喜欢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这样的包,它可以与源代码中的docstring完全一致。

如果您想投资您的用户,请教他们less(或more)命令,使用这几个热键搜索/字符串,跳转到下一个匹配项n,将一个匹配N返回到顶部gg或底部G。 <{1}}或h是您的朋友,H是您的安全休息。

享受在命令行上的生活。