我有更好的 Python 文档吗？更有条理？答案

【问题标题】：I there a better Python documentation? More structured?我有更好的 Python 文档吗？更有条理？
【发布时间】：2019-07-06 22:14:22
【问题描述】：

我猜这个问题已经被问过了，但我没有找到它。

我过去曾使用过 Java 和 PHP，我相信它们的语言文档结构更好。至少他们的 API。

如果您查看 Java 的 API，那真是太棒了。非常好的结构和可预测的。它还允许你找到你不知道存在的新东西。我正在考虑这个https://docs.oracle.com/javase/7/docs/api/。

PHP 的结构不太好，但它的效果很好。我说的是这个：https://www.php.net/manual/en/。

现在，如果您看到 Python 的等价物（至少是我发现的 https://docs.python.org/3/index.html），那感觉就像一个很长的教程。从我的角度来看，搜索东西很困难，而且没有真正的等级组织。当您阅读有关函数的内容时，当我真正在寻找摘要时，还会有很多描述内容的文本。以https://docs.python.org/3/library/string.html 为例，请参阅“格式化字符串语法”部分，感觉它应该转到专门针对该主题的其他地方。

所以我的问题是：Python API 的结构是否与 JAVA 类似？

【问题讨论】：

它们具有可比性，Javadocs 可能更胜一筹。真正的问题是在您没有意识到自己想要的时候找到您想要的东西，而这最好由搜索引擎 + stackoverflow 提供。
您可能需要Library reference，您可以在主文档页面上找到该链接。
Java 严格遵循对象模型，因此其 API 以相同的格式呈现每个类。虽然 Python 具有可比较的类层次结构（一切都是类的实例），但它允许各种编程范式，并且文档反映了这一点。所以是的，许多模块的文档看起来更像是一个深入的使用教程，而不是正式的类描述。

标签： python api documentation

【解决方案1】：

Python 在标准库中有一个几乎等效的 Javadoc，称为 pydoc。

您可以使用命令将其作为 Web 服务器启动

$ python -m pydoc -b

（或者-p 80如果随机端口给你带来麻烦，那么去http://localhost）

这应该会打开一个网络浏览器，让您可以浏览标准库以及您碰巧安装的任何其他包。

请注意，您还可以使用help() 实用程序从 Python 的交互式 shell/REPL 中获取所有这些信息。

>>> help()

假设你想找到函数来处理字符串，例如strip()。使用这两种方法你会如何找到这个函数？

$ python -m pydoc str

或

>>> help(str)

将显示str 类型的帮助，包括其所有方法。

如果您不知道字符串的类型为 str，您可以创建一个并询问其类型：

>>> type("foo")
<class 'str'>
>>> help(type("foo"))

要查看对象属性的更紧凑目录，可以使用

>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

但既然你已经知道名字是strip()，你可以就那个对象寻求帮助。

>>> help(str.strip)

这将显示方法签名和文档字符串，如果有的话。

使用 Pydoc 的 Web 服务器，单击起始页上“内置模块”中的 builtins 链接，然后单击 str 链接以查看完全相同的信息，因为 help() 也由 pydoc 提供.

还有一个“搜索”和一个“获取”栏。在“获取”栏中输入 str.strip 会直接进入，就像使用 help(str.strip) 一样。

这是很棒的信息。谢谢。有没有什么地方在网上发布的？这样就不用在本地启动服务器了吗？

我不知道。鉴于 https://docs.python.org 似乎没有什么意义。本地服务器的优势在于它会根据您启动它时使用的解释器准确记录系统上安装的内容，即使您安装了多个 Python 版本（或使用安装了不同软件包的 virtualenvs）。甚至标准库也可能因操作系统或发行版以及（从源代码编译时）编译时可用的 C 库而异。

【讨论】：

这是很棒的信息。谢谢。有没有什么地方在网上发布的？这样就不用在本地启动服务器了？
@glich 假设您想找到对字符串执行操作的函数，例如 strip()。使用这两种方法你会如何找到这个函数？
请注意，我喜欢 W3Schools，那里也有不错的 Python 文档 (w3schools.com/python)。

【解决方案2】：

不确定这是否正是您想要的，但在 python REPL 环境中，您可以使用 help 来获得更多信息：

如果您输入具体的方法名称，您可以获得更多信息，即help(str.format)：

【讨论】：

很好，谢谢 :)