gpt4 book ai didi

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

转载 作者:太空宇宙 更新时间:2023-11-03 18:25:01 26 4
gpt4 key购买 nike

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

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

最佳答案

有多个选项可用于记录用 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

还有其他参数解析器,例如 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 这样的包,它可以与源代码中的文档字符串完美一致。

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

享受命令行生活。

关于python - 如何使用 sphinx 为 1 文件 python 项目(脚本,无模块)生成文档?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/23371610/

26 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com