如何使用Sphinx为1文件python项目（脚本，无模块）生成文档？

Question

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

我已经设法生成了所有就绪的sphinx文档，但是如何确定我的文件是脚本而不是模块？

Answer 1

使用Python编写的命令行工具文档记录有多个选项：

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

（我不声明，此列表是完整的）

从命令行打印帮助字符串

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

我强烈建议您使用docopt来解析命令行，因为它带给您所有docopt -在源代码中具有docstring（作为模块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 。

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

编写README.rst非常容易，并且具有优势，即在github和bitbucket上，您的项目会自动阅读，从而获得了很好的可读性介绍。

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

安装docutils时：

$ pip install docutils

您将获得一堆命令，这些命令可让您将README.rst转换为不错的命令。 我从该集合中使用的唯一命令是rst2html （在Windows上为rst2html.py ，您必须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之类的docopt它可以与源代码中的docstring完美地内联。

而且，如果您想对用户进行投资，请用很少的热键来教他们less （或more ）的命令来搜索/查找字符串，跳至下一个出现n ，返回一个出现N ，到达顶部gg或底部G h或H是您的朋友，请q安全中断。

享受生活在命令行上。