有更好的Python文档吗？更有结构性的？

Question

有更好的Python文档吗？更有结构性的？

pythonapidocumentation

7

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

我曾经使用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 ，看看“格式化字符串语法”部分，感觉它应该放在专门讨论该主题的其他地方。

所以我的问题是：是否有类似于JAVA中所做的方式来构建Python API的结构？

- loco.loop

它们是可比的，Javadocs 可能更优秀。真正的问题在于当你不知道自己需要什么时如何找到它，这可以通过搜索引擎和 StackOverflow 最好地解决。 - President James K. Polk

1

您可能需要查看库参考，您可以在主文档页面上找到该链接。 - chepner

Java严格遵循面向对象模型，因此其API以相同格式呈现每个类。虽然Python具有可比较的类层次结构（一切都是类的实例），但它允许各种编程范式，并且文档反映了这一点。因此，许多模块的文档看起来更像是深入的如何使用教程，而不是正式的类描述。 - hpaulj

2个回答

1

我不确定这是否完全符合您的需求，但在Python REPL环境中，您可以使用help命令，以获得更加准确的信息：

如果您输入特定的方法名称，您可以获得更多信息，例如help(str.format):

- Sash Sinha

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- gilch · Accepted Answer

Python在标准库中有一个类似于Javadoc的近似等效物，称为pydoc。

您可以使用以下命令启动它作为Web服务器：

$ python -m pydoc -b

(或者使用 -p 80 如果随机端口有问题，然后前往 http://localhost)

这将打开一个网页浏览器，让你探索标准库以及你安装的其他任何包。

请注意，您也可以使用 Python 的交互式 shell/REPL，使用 help() 工具获取所有此信息。

>>> 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版本（或使用具有不同软件包的虚拟环境），标准库也可能因操作系统或发行版而异，并且（在从源代码编译时）可用的C库也可能因编译时可用的C库而异。