Python文档（应该更好吗？） [英] Python Documentation (should be better?)
问题描述
这篇文章只是我在Python上与我的
同事讨论的结果。如果您不感兴趣，请跳过它。
在我的工作中，我们正在从头开发产品。它完全是模块化的，模块通过SOAP进行通信。正因为如此，我们可以用我们选择的任何语言实现单个模块（只要
他们有很好的SOAP库）。我选择用Python做我的全部，因为我是一个很棒的Python粉丝男孩。当然，我试图让我的同事去尝试Python。
我和一个人签了一个协议：我用PHP编写了一个模块，他将用/或
用Python写一个。
完成后，我们讨论了语言的优缺点。
搞笑，Python（文档）的内容是PHP''强项。 PHP
手册非常易于导航，其搜索功能非常好。
与Python相比，你必须使用教程。作为
手册。此外，教程只是...一个教程，它不是一本手册。
它没有像手册那样有条理，而且不像手册那样全面，
hell ，raw_input（）在第7章中甚至没有提到。输入和输出。
现在是真正的踢球者。一些模块文档甚至没有列出简单的用例甚至整个API。当我的同事带着
这个投诉来找我时，我的回答是哦，只需加载解释器，导入
模块并在其上调用dir（）。然后实例化一些对象并在它们上面调用dir（）
。我对Python的迷恋使我无法意识到学习使用API的方法非常荒谬。不用说b
，我的同事对这句话的反应让我失去了兴趣。但实际上这是真实的。你们有多少人通过启动翻译来学习模块
和play围绕着它并使用dir（）？
下一个投诉并不是关于文档的。为什么Python没有CPAN
或PEAR？很多次我找到了一个模块，没有找到它，
开始自己编写，然后在谷歌上偶然发现它......唉！
别误会我的意思，我喜欢Python。语言本身是首屈一指的（我还没有尝试过Ruby），但这种经历让我想起了未来Python的成功。甚至我，一个庞大的Python倡导者，已经开始使用PHP更频繁，因为我可以很容易地找到记录良好的，半bn的半官方模块，并且学习PHP是一个微风与
非常棒的PHP手册。
你觉得怎么样？
This post is just the culmination of my thoughts and discussions with my
coworkers on Python. If you are not interested, please skip over it.
At my work, we are developing a product from scratch. It is completely
modular and the modules communicate via SOAP. Because of that, we can
implement individual modules in any language of our choosing (so long as
they have good SOAP libs). I chose to do all mine in Python because I''m a
huge Python fan boy. Naturally, I tried to get my coworkers to try Python.
I made an agreement with one: I write one of my modules in PHP and he will
write one in Python.
After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP''s strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
Its not organized like a manual and its not comprehensive like a manual,
hell, raw_input() isn''t even mentioned in Chapter 7. Input and Output.
Now for the real kicker. Some of the module documentation doesn''t even list
simple use cases or even the entire API. When my coworker came to me with
this complaint, my response was "oh, just load the interpreter, import the
module and call dir() on it. Then instantiate some objects and call dir()
on them also". My infatuation with Python had kept me from realizing the
sheer ridiculousness of that method to learn to use an API. Needless to
say, my coworker''s reaction to that statement snapped me out of it. But
its the truth. How many of you learn a module by starting the interpreter
and "playing" around with it and using dir()?
The next complaint isn''t really about documentation. Why isn''t there a CPAN
or PEAR for Python? So many times I''ve search for a module, not found it,
started to write it myself, then later stumble across it on Google...ugh!
Don''t get me wrong, I love Python. The language itself is second to none (I
haven''t tried Ruby yet), but this experience has left me wondering about
the future success of Python. Even I, a huge Python advocate, has started
to use PHP more often simply because I can find well documented,
semi-official modules very easily and learning PHP is a breeze with the
awesome PHP manual.
What do yall think?
推荐答案
我认为Python的文档真的很摇滚。这很奇怪，为什么当lib API是我考虑的时候你会参考
教程文档。
如果您使用的是Windows，那么包含的文档浏览器非常好
...
I think Python''s doc really rock. It''s odd, why do you refer to the
tutorial when the lib API is what I''d consider "the docs".
If you''re using Windows, then the doc browser included is pretty good
too...
Christopher J. Bottaro写道：
Christopher J. Bottaro wrote:
[...]
有趣的是，Python（文档）的内容是PHP的优点。
PHP手册非常易于导航和它的搜索功能
效果很好。与Python相比，你必须使用
教程。作为手册。此外，该教程只是...一个
教程，它不是一本手册。
这个教程很棒恕我直言，是的，它绝对不是一个
参考指南。但是在线图书馆有什么问题
参考或其pdf等价物？为什么你不使用
python.org" search" （屏幕右上角）？
现在为真正的踢球者。有些模块文档甚至没有列出简单的用例甚至是整个API。
有时候，''缺失''界面是（表面上）隐藏的
。关于DocTestCase类的doctest中的示例
（引自库ref）：
"""
Under封面，DocTestSuite（）创建一个unittest.TestSuite出
doctest.DocTestCase的实例，以及DocTestCase是
的unittest.TestCase生成子类。 DocTestCase在这里没有记录（它是一个内部的
细节），但研究它的代码可以回答关于单元测试集成的确切细节的问题。 />
"""
您是否可以更具体地了解模块/包
缺少适当的示例/文档？
当我的同事带着
这个投诉来找我时，我的回答是哦，只需加载解释器，
导入模块并调用dir（）就可以了。然后实例化一些
对象并在它们上面调用dir（）。我对Python的迷恋使我无法实现该方法学习使用API的纯粹荒谬。毋庸置疑，我的同事对那个
声明的反应使我摆脱了它。但它的真相。你们当中有多少人通过启动翻译来学习
模块和玩。使用它并使用dir（）？
[...]
Funny, the con of Python (documentation) is PHP''s strong point.
The PHP manual is extremely easy to navigate and its search feature
works great. Contrast that with Python, where you have to use "the
tutorial" as the manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
The tutorial is great IMHO and yes, it is definitely not a
reference guide. But what''s wrong with the online library
reference or its pdf equivalent ? And why don''t you use the
python.org "search" (top right of the screen) ?
Now for the real kicker. Some of the module documentation doesn''t
even list simple use cases or even the entire API.
Sometimes the ''missing'' interface is (superficially) hidden
on purpose. Example in doctest about the DocTestCase class
(quoted from the library ref) :
"""
Under the covers, DocTestSuite() creates a unittest.TestSuite out of
doctest.DocTestCase instances, and DocTestCase is a subclass of
unittest.TestCase. DocTestCase isn''t documented here (it''s an internal
detail), but studying its code can answer questions about the exact
details of unittest integration.
"""
Could you be more specific about the modules/packages
that lack proper examples/documentation ?
When my coworker came to me with
this complaint, my response was "oh, just load the interpreter,
import the module and call dir() on it. Then instantiate some objects and call dir() on them also". My infatuation with Python had kept me from realizing the sheer ridiculousness of that method to learn to
use an API. Needless to say, my coworker''s reaction to that statement snapped me out of it. But its the truth. How many of you learn a
module by starting the interpreter
and "playing" around with it and using dir()?
您也可以使用帮助而不是dir，或者在shell中直接使用
pydoc：
python>>> help（math）
python>>>帮助（数学）＃如果''数学'已经导入了
bash
You may also use "help" instead of "dir", or directly
pydoc in a shell:
python>>> help("math")
python>>> help(math) # if ''math'' has already been imported
bash
pydoc math
这个那种文件系统适合我（无论如何，它比原始目录更好
）。它支持''点缀引用''
描述对象的路径（即
package.subpackage.module.holder.object），这是恕我直言/>
方便。
干杯，
SB
pydoc math
This kind of documentation system suits me (it is far better
than a raw dir anyway). It supports a ''dotted reference''
description of the path to the objects (ie
package.subpackage.module.holder.object) that is IMHO very
convenient.
Cheers,
SB
这篇关于Python文档（应该更好吗？）的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
