- android - 多次调用 OnPrimaryClipChangedListener
- android - 无法更新 RecyclerView 中的 TextView 字段
- android.database.CursorIndexOutOfBoundsException : Index 0 requested, 光标大小为 0
- android - 使用 AppCompat 时,我们是否需要明确指定其 UI 组件(Spinner、EditText)颜色
我有一个Python项目,它存储在一个文件中,它是一个命令行工具。
我已经成功使用 sphinx 生成了文档,但如何确定我的文件是脚本而不是模块?
最佳答案
有多个选项可用于记录用 Python 编写的命令行工具:
rst2html
转换为 html(我不声称,这个列表是完整的)
这是迄今为止最容易访问的文档形式,因为安装该程序的每个人都可以显示它。
我强烈建议使用 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
。
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 是 reStructuredText 的出色扩展,并用它编写了几本技术小册子 - 它提供了出色的交叉引用语法,我喜欢它。
但对于命令行工具,我认为它太过分了。
有关如何使用 Sphinx 的说明,请参阅他们的精彩文档。
Sphinx 很棒,但对于命令行工具来说似乎有点过分了。
reStructuredText README.rst 应该是任何 Python 项目的必备部分,无论大小如何,当您忘记项目的所有内容时,将您认为方便的所有内容都放在那里。
另一方面,我以 html 形式向用户提供了一组页面,但我不确定他们真正阅读这些页面的频率。人都是懒惰的。
命令行上的帮助选项文档似乎最适合我。目前,您需要帮助(在命令行上输入),您就可以得到它。借助像 docopt
这样的包,它可以与源代码中的文档字符串完美一致。
如果您想对用户进行投资,请教他们less
(或more
)命令,使用这几个热键来搜索/
对于字符串,跳转到下一个匹配项 n
,返回一个匹配项 N
,跳转到顶部 gg
或底部 G
>。 h
或 H
成为您的 friend ,q
成为您的安全漏洞。
享受命令行生活。
关于python - 如何使用 sphinx 为 1 文件 python 项目(脚本,无模块)生成文档?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/23371610/
我有一个 .sln 文件,里面有几个项目。为了简单起见,让我们称它们为... 项目A 项目B 项目C ...其中 A 是引用 B 和 C 的主要项目。我的目标是更新我的构建脚本,为 ProjectA
我安装了 Magento,我想知道如何生成完整的 API 文档,例如 http://docs.magentocommerce.com/ 上的文档是使用 phpdoc 生成的。 Magento 中是否包
我通常使用jetbrains family ide。在为函数创建文档时非常有用,只需输入 /** 如何在创建文档时创建自定义标签,例如@date标签。 最佳答案 JavaScript、Java: st
我正在尝试使用 jOpenDocument library创建文档。我已经执行了创建电子表格的示例 - 代码编译并运行正常,但当我尝试使用 Excel Office 2012 或 Google Doc
如标题。 有没有介绍HTML DOM构造的图片? 最佳答案 DOM(文档 对象模型)从文档 节点开始。它被称为“根节点”。 观察下面的树(括号中对应的nodeType): [HTMLDocument]
我喜欢 ColdFusion Builder。但我不喜欢帮助只有 CF9 文档。有什么方法可以将其更改为拥有 ColdFusion 8 文档? 最佳答案 http://livedocs.adobe.c
这个问题在这里已经有了答案: What is the consequence of this bit of javascript? (4 个答案) 关闭 9 年前。 我看到一些 jQuery 脚本嵌
我有一个 XML 文件,其中包含需要在 Word 文档中填充的数据。 我需要找到一种方法来定义一个模板,该模板可用作从 XML 文件填充数据并创建输出文档的基线。 我相信有两种方法可以做到这一点。 创
我正在尝试查找有关如何使用 AVAudioEngine 的详细文档。有谁知道我在哪里可以找到它? 我找到了这个,但与文档丰富的 UI 内容相比,它似乎非常简陋。 https://developer.a
我对 Tensorflow 文档越来越感到恼火和沮丧。我在谷歌上搜索了有关 的文档 tf.reshape 我被定向到一个通用页面,例如 here 。我想查看 tf.reshape 的详细信息,而不是整
我正在学习本教程:http://moxleystratton.com/clojure/clojure-tutorial-for-the-non-lisp-programmer 然后遇到了这个片段: u
如何在 swagger 中为对象数组编写文档。这是我的代码,但我不知道如何访问对象数组中的数据。 { "first_name":"Sam", "last_name":"Smith",
是否有针对 Javascript 的 JavaDocs 之类的东西?当我在 netbeans IDE 中按 ctrl+space 时 写javascript,指定对象的javascript文档就出来了
关闭。这个问题不符合Stack Overflow guidelines .它目前不接受答案。 我们不允许提问寻求书籍、工具、软件库等的推荐。您可以编辑问题,以便用事实和引用来回答。 关闭 5 年前。
我需要 JavaScript 中的 heredoc 之类的东西。你对此有什么想法吗?我需要跨浏览器功能。 我发现了这个: heredoc = '\ \ \ zzz\ \
WSDL 文档是包含一系列的,可描述某个 web service 的定义的,简单的 XML 文档 WSDL 文档结构 WSDL 文档用下表这些主要的元素来描述某个 web service 的
是否有 ocropus 的文档? 我正在寻找对以下功能的解释: make_SegmentPageByRAST(): segment() RegionExtractor(): setPageLines(
这个问题在这里已经有了答案: Understanding events and event handlers in C# (13 个回答) 4年前关闭。 我正在使用 NRECO 和 ffmpeg 对视
我正在尝试访问工作服务器以与名为 Spotfire 的应用程序一起使用。我的同事把这个传给我,现在已经休息了几个星期,我对他的建议有意见。 实际上,当我通过 localhost 运行我的 Web 应用
Elm 文档没有给出示例用法,因此很难理解类型规范的含义。在几个地方,我看到“a”用作参数标识符,例如 Platform.Cmd : map : (a -> msg) -> Cmd a -> Cmd
我是一名优秀的程序员,十分优秀!