我有一个存储在一个文件中的python项目,它是一个命令行工具。
我设法用sphinx allready生成文档,但是如何确定我的文件是脚本而不是模块?
答案 0 :(得分:1)
有多种选项可用于记录用Python编写的命令行工具:
rst2html
转换为html (我没有声称,此列表已完成)
从命令行打印的这是迄今为止最容易访问的文档形式,因为安装程序的每个人都可以显示它。
我强烈建议使用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
还有其他参数解析器,例如plac
或argparse
。就个人而言,我最喜欢docopt
。
rst2html
编写README.rst非常简单并且具有优势,在github和bitbucket上,您可以获得对项目的可读性介绍,因为它会自动呈现。
它也比Sphinx项目简单得多,你不必使用多个文件,只有一个。
安装docutils时:
$ pip install docutils
你得到一堆命令,可以让你将README.rst转换成好的东西。我在这个集合中使用的唯一命令是rst2html
(在Windows上它作为rst2html.py
,你必须发挥一点才能使它工作,但它绝对值得。)
为您的README.rst
:
$ rst2html README.rst README.html
我是通过我的vim
编辑器进行的,它更简单:!rst2html % %.html
生成README.rst.html
文件的内容。
我认为Sphinx是reStructuredText的一个很好的扩展,并且已经创作了几本技术手册 - 它提供了很好的交叉引用语法,我喜欢它。
但对于命令行工具,我认为它有点过分。
有关如何使用Sphinx的说明,请参阅他们的精彩文档。
Sphinx非常棒,但对于命令行工具来说似乎有些过分。
reStructuredText README.rst必须是任何Python项目的必备部分,无论大小如何,当你忘记项目的所有内容时,请将所有内容放在手边。
另一方面,我已经用html为我的用户提供了一组页面,我不确定,他们多久经常阅读它。人们很懒。
命令行上的帮助选项上的文档似乎最适合我。目前,你需要帮助(在命令行输入),你有它。对于像docopt
这样的包,它可以与源代码中的docstring完全一致。
如果您想投资您的用户,请教他们less
(或more
)命令,使用这几个热键搜索/
字符串,跳转到下一个匹配项n
,将一个匹配N
返回到顶部gg
或底部G
。 <{1}}或h
是您的朋友,H
是您的安全休息。
享受在命令行上的生活。