Re: Python Documentation (should be better?)
Overall organization is definitely an issue, at least for newer users.
As an occasional python user I remain constantly in a mode of having to
look up basic terminology for examples and exact spelling of terms in
order to knock out a quick script. I feel very much like Mr. Bottaro
that the docs, while quite good in some ways, can be frustrating and
inconsistent at times. Here's a link to a concrete and mostly real
stream of consciousness example of using the docs: (rather long)
http://home.pacbell.net/dl_brown/input_something.txt
Many responses from experienced users that show how to find a certain
piece of information really miss the point by a wide margin. It's nice
that they can find the information easily of course. It's those who
don't have the experience who can have more trouble. If the docs,
especially the tutorial, are intended to help those with limited
experience they should try to be a little more fool-proof with regard
to indexing and searching, and also have more basic examples.
Here are a couple specific suggestions for improvements:
-- Please add the basic input methods to the Input/Output section of
the tutorial (see previous link and the original post for this thread)
-- Add a Doc_Feedback button on many of the documentation pages so when
people have problems finding or understanding something they can
immediately and easily send feedback about that specific problem.
-- Consider at least renaming and reordering the main doc page links to
highlight the most important 2 or 3 docs for people who don't know
where to start. Right now the doc structure is too flat and
disconnected in my opinion. It needs to act more like a funnel. Today
I have to pick which document might contain the information I need and
if I'm wrong I probably won't find what I'm looking for quickly. The
present structure seems to work ok for experts, not so well for
novices.
-- If doc maintainers believe the better approach for most people is to
just search (I don't) then move the doc links to the side, put them in
a smaller font, and put a big search box in the middle of the docs
page. Right now search is in the far corner so the implicit
understanding is that it's not the first thing to try.
-- Find clearer names/descriptions for some documents. For example
maybe it's just me but what is the _Library_ Reference? I know about
python modules and python language, etc. What are python libraries.
Or is it just intended to mean generically a book in a library of
python books? There was some discussion and debate about which doc was
the Manual Perhaps one of the docs or a reorganized combination
should be called the Python Online Manual if Manual Implies that it's
the go-to book.
-- And finally, I recall the last time I tried to figure out how to do
something with a date value I looked in the datetime module. There are
lots of sophisticated tools apparently but I really never grasped how
to go about using them. A couple basic examples of what can be done
with the tools would be nice.
-- TkInter... (ok I'm done now)
help(tKinter)
Traceback (most recent call last):
File stdin, line 1, in ?
NameError: name 'tKinter' is not defined
help('tkinter')
no Python documentation found for 'tkinter'
help('tKinter')
no Python documentation found for 'tKinter'
help('TkIinter')
no Python documentation found for 'TkIinter'
help('TkInter')
no Python documentation found for 'TkInter'
help('Tkinter')
Help on module Tkinter: (don't believe it)
-- David
--
http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
bruno modulix a écrit : snip I fail to see why would it would be better to have to open a browser, go to python.org, go to the doc, find the right link etc instead of just typing dir(xxx) and/or help(xxx). I fully agree with you. I just suspect that you are not more than me a web developper. I suppose that for this kind of guys, using a browser connected to the web is the more natural way to go ... and PHP developers are those kind of guys. This is to say that comparing the doc of PHP to the one of Python is somewhat not more relevant that comparing PHP to Python as languages. Probably even less because: - PHP developers are naturally presentation oriented. - it's easier to give good exemples when everybody is working in about the same area. Python is a very flexible tool and that makes things sometimes more difficult ... but worthy anyway. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote:
Hi All--
Yes. There are multiple ways I can correct myself, some, I'm sure,
involving chains and whips.
Well, if you like it...
But you're all missing the point:
Christopher is right! Python docs are not as good as PHP docs.
That's a POV, not a fact.
Why
not? Why do I have to be told Hey, there are fifty ways to get what
you want! when I should be able to go to the main doc page and SEE the
right link to click.
I fail to see why would it would be better to have to open a browser, go
to python.org, go to the doc, find the right link etc instead of just
typing dir(xxx) and/or help(xxx).
--
bruno desthuilliers
python -c print '@'.join(['.'.join([w[::-1] for w in p.split('.')]) for
p in '[EMAIL PROTECTED]'.split('@')])
--
http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
bruno modulix wrote: I fail to see why would it would be better to have to open a browser, go to python.org, go to the doc, find the right link etc instead of just typing dir(xxx) and/or help(xxx). Well, for those with Windows machines, the documentation is a simple Start-All Programs-Python-Python Manuals. I'm somewhat amused that the Docs don't come standard with other platforms. I guess they figure if you're compiling from source, you'd download them to the local machine separately. That said, I have no clue if PHP provides a local copy of the docs. It seems doubtful, given how people have trumpeted the user-supplied comments aspect of the PHP docs. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham a écrit : (snip) BTW, my tortured method is quicker than Bruno's, because to use his method I'd have to start the interactive interpreter. start the interactive interpreter ??? What do you mean, start the interactive interpreter ??? It's *always* started as a part of your development environnement, and not more than one keystroke away, isn't it ??? -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
bruno I fail to see why would it would be better to have to open a bruno browser, go to python.org, go to the doc, find the right link etc bruno instead of just typing dir(xxx) and/or help(xxx). Actually, you frequently don't even have to enter the Python interpreter. Executing pydoc -p 8080 will start up a web server at http://localhost:8080/ that will allow you to browse the builtin docs (module/package/class/function docstrings). Since 2.4, the doc display for most core modules and packages should also contain a link to the standard doc. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham [EMAIL PROTECTED] writes: Hi All-- The Python docs are not ideal. I can never remember, for instance, where to find string methods (not methods in the string module, but methods with ''), but I can remember a tortured path to get me there [...] The answer to 80% of where is it questions re the Python docs is Section 2 of the Library Reference. The other 15% include __special__ methods (they're almost all in the Language Reference), miscellaneous functions that aren't in the module you might expect, and questions about language semantics (which can sometimes be hard or impossible to answer by reading the docs, because, when they're documented at all, they're sometimes in some collection of PEPs, articles and mailing list posts). The last 5% are PEBKAC. John -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Greg Ewing [EMAIL PROTECTED] writes: Ivan Van Laningham wrote: Hi All-- The Python docs are not ideal. I can never remember, for instance, where to find string methods (not methods in the string module, but methods with '') Curiously I had the same problem just the other day, except with list instead of string. I think the problem is that the sections on the actual built-in types (list, str, dict, etc.) are one level too far down to appear in the table of contents of the Library Reference. If things could be rearranged so that their names actually appeared in the table of contents, I think it would make a big difference in this area. [...] +1 John -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro [EMAIL PROTECTED] writes: [...] 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). Oh dear! Have fun wink [...] 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. Did they renumber it at some point? In my copy: 7. Optional Operating System Services. Ohh, you mean the Language Reference? I've been working full time as a Python programmer for over a year (and using Python for many years before that), and I've certainly never sat down and read it start to finish (nor even read the whole thing in pieces, over the years). [...] 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()? I don't. dir(), the interactive prompt, module inspect c. can all be very handy at times, though. 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! Fair point, but PyPI (pypi.org) is growing (and now very easy to use), and the Vaults of Parnassus was still there last time I looked. [...] 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. [...] I don't recognize the problem with basic language features or module docs. There is perhaps a problem with docs for language features on a more advanced level than you complain about, though. John -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro [EMAIL PROTECTED] writes: [...] By the way, did you try the .chm? John -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
In article [EMAIL PROTECTED], Greg Ewing [EMAIL PROTECTED] wrote: Curiously I had the same problem just the other day, except with list instead of string. I think the problem is that the sections on the actual built-in types (list, str, dict, etc.) are one level too far down to appear in the table of contents of the Library Reference. If things could be rearranged so that their names actually appeared in the table of contents, I think it would make a big difference in this area. There should be a doc bug I submitted that covers that, but I don't have time to look for it. -- Aahz ([EMAIL PROTECTED]) * http://www.pythoncraft.com/ And if that makes me an elitist...I couldn't be happier. --JMS -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Greg Ewing wrote: Curiously I had the same problem just the other day, except with list instead of string. I think the problem is that the sections on the actual built-in types (list, str, dict, etc.) are one level too far down to appear in the table of contents of the Library Reference. If things could be rearranged so that their names actually appeared in the table of contents, I think it would make a big difference in this area. I would be satisfied if that table of contents page simply listed ALL the subsections, indented appropriately. (As it is, it only lists them to two levels deep.) This would also be handy in that if I knew I wanted to go to Mutable Sequence Types, I could click on that directly from the index instead of having to click through Sequence Types first. -- --OKB (not okblacke) Brendan Barnwell Do not follow where the path may lead. Go, instead, where there is no path, and leave a trail. --author unknown -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote: Hi All-- John Bokma wrote: Ivan Van Laningham wrote: Python docs are not as good as PHP docs. Oh my. I hope you are just making that up. PHP documentation is guesstimated on how PHP works on average. Add the online comments clutter and you probably are better off reading the source. I didn't write that; I was riffing on Christopher's contention that Python's docs ought to be awesome, which I think ought to be true. Apologies for the misquoting :-) I couldn't even imagine that the statement could be true in anyway. I've read the introduction, and Dive into Python, which I highly recommend, and I liked what I read :-). -- John MexIT: http://johnbokma.com/mexit/ personal page: http://johnbokma.com/ Experienced programmer available: http://castleamber.com/ Happy Customers: http://castleamber.com/testimonials.html -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Paul Some parts of the lib doc are better than others. The only way to Paul understand SocketServer, for example, is to read the long comment Paul at the beginning of the source file. I've been wanting to get Paul around to merging that with the doc writeup and adding some Paul examples. Thanks for the suggestion. I just incorporated the module doc string into the SocketServer doc (CVS HEAD and 2.4 release branch). Paul Tkinter, as well, is practically undocumented as far as the base Paul distro is concerned, but there's some good docs for it elsewhere Paul on the web. I'll let someone else tackle that one. ;-) Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan I get that. My question, cleverly concealed in a rant, was, Why Ivan does clicking on the Documentation link at python.org NOT take me Ivan to docs.python.org? I almost changed that link, but then reconsidered. Compare http://docs.python.org/ with http://www.python.org/docs/ The former is just the main documentation that's part of the Python distribution. The latter contains links to lots of supplementary material, much of which is not part of python.org. The original functional goal of the http://docs.python.org/ URL was to provide a cleaner isolation of just the facts, Ma'am so that Google could do a better job presenting documentation search results. Previously, it was impossible to separate the mailing list archives from the documentation proper in Google searches. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Steven Bethard wrote: Ivan Van Laningham wrote: The Python docs are not ideal. I can never remember, for instance, where to find string methods (not methods in the string module, but methods with '') Hmmm... Well going to http://docs.python.org/ and typing string methods into the search box gives, as the first hit: http://docs.python.org/lib/string-methods.html Even if you just search for string, that URL is the second hit, and pretty clearly the right one from the title. STeVe Heh, searching dict methods didn't produce the correct results on the first page. dictionary methods did. searching for append returned the array's module page as the first result, and list's module page as the 8th result. Search for static came up with nothing. Search for staticmethod came up with the built-in-funcs page, from which I had to search again for staticmethod. The search mechanism isn't all that great (imo anyways). Honestly, neither is the PHP one, except when you are only searching the function list. Then its the bomb. I also like how each PHP function gets its own page and each page is full of examples. And I love how each page shows related functions. Granted its easier to do the function list search for PHP because there are no namespaces or classes, but still I think Python could do something similar. Say for instance search for append and it will come back with a page for list's append, a page for array's append, etc. My idea for a manual's table of contents: 1. Variables 2. Conditional and Branching Constructs 3. Looping Constructs 4. Functions 5. Modules 6. Classes 7. Exceptions 8. Built-in 8.1 Functions 8.2 Types Of course there should be more detailed sublevels. The tutorial (at least chapters 3-11) make a good (partial) manual. I think those chapters should be the basis for a real manual vs. a tutorial. If I wanted to learn about types in Python, where do I look? The PHP manual has a whole section on the built-in types, how to get the type of a var, how to change cast the type of a var, etc. I think that is such an important and basic part of any language, yet its scattered all over Python documention, difficult to find (i.e. not in a manual, but the library reference). I guess what I'm trying to say is that there should be a manual which is half way between the tutorial and the library reference, that is organized more like a traditional manual (whatever that means, right?) and is more easily searchable. -- C -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Steven Bethard wrote: Christopher J. Bottaro wrote: Contrast that with Python. First off there is no search mechanism built into the documentation page (yes I know you can google it, but that just doesn't feel right). Um, are you looking at the current documentation page? http://docs.python.org/ In the upper right hand corner, I see a box entitled Search: and a button that says submit. Oops. I link directly to the tutorial and library reference...=) STeVe -- C -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro [EMAIL PROTECTED] writes: because there are no namespaces or classes, but still I think Python could do something similar. Say for instance search for append and it will come back with a page for list's append, a page for array's append, etc. A seperate page for each method of every class? Ouch. I think that's serious overkill. Having the entries for the methods in the pages be labelled, so that a search could return a direct link to the appropriate paragraph, that would be a major improvement. If I wanted to learn about types in Python, where do I look? The PHP manual has a whole section on the built-in types, how to get the type of a var, how to change cast the type of a var, etc. I think that is such an important and basic part of any language, yet its scattered all over Python documention, difficult to find (i.e. not in a manual, but the library reference). Python variables don't have types. Python objects have types. Python further confuses the issue by overloading types to mean builtin types, which are different classes, which can both instantiate as a variable. If you're doing things Pythonically, you generally don't care what type a variable has - you care that it supports the operations you want. Changing the type of an object is either impossible or dificult, depending on the object - and not to be undertaken lightly. What I'm trying to say is that type just isn't as important a concept in Python as it is in other languages. PHP, for instance, apparently has a number of automatic conversions between types if various operations are applied, so you have to care what type an object is or risk getting it converted accidently. Python doesn't do that. Many languages have typed variables, so everything you do will depend on the type of the variable. Python doesn't do that. Some OO languages conflate types and classes, and use isinstane for type checking. Python doesn't do that. All that python cares about - and all that you really need to care about - is that the object referenced by the variable support the features you want to use. I guess what I'm trying to say is that there should be a manual which is half way between the tutorial and the library reference, that is organized more like a traditional manual (whatever that means, right?) and is more easily searchable. Given that Python hides the difference between user-defined objects and built-in objects, it's not clear to me that anything other than the current system, with all the classes/types in one place, makes sense. That's not to say the documentation can't be improved. I'm just not convinced that a manual pulling in parts from multiple different places is an improvement. That said, I'd like to ask what's wrong with the language reference? It provides a nice reference on the syntax and semantics of the language. What does the tutorial provide that you can't get from the Language Reference? mike -- Mike Meyer [EMAIL PROTECTED] http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Mike Given that Python hides the difference between user-defined Mike objects and built-in objects, it's not clear to me that anything Mike other than the current system, with all the classes/types in one Mike place, makes sense. Maybe the Module Index should be renamed Module/Type Index and embellished with the builtin types, so that you'd find float (builtin), string (builtin), dict (builtin), etc. in the appropriate alphabetical positions. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Skip Montanaro [EMAIL PROTECTED] wrote in message news:[EMAIL PROTECTED] Maybe the Module Index should be renamed Module/Type Index and embellished with the builtin types, so that you'd find float (builtin), string (builtin), dict (builtin), etc. in the appropriate alphabetical positions. +1 TJR -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
On 5/12/05, Terry Reedy [EMAIL PROTECTED] wrote: Skip Montanaro [EMAIL PROTECTED] wrote in message news:[EMAIL PROTECTED] Maybe the Module Index should be renamed Module/Type Index and embellished with the builtin types, so that you'd find float (builtin), string (builtin), dict (builtin), etc. in the appropriate alphabetical positions. +1 TJR +1 Bill Mill bill.mill at gmail.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Skip Montanaro wrote: Mike Given that Python hides the difference between user-defined Mike objects and built-in objects, it's not clear to me that anything Mike other than the current system, with all the classes/types in one Mike place, makes sense. Maybe the Module Index should be renamed Module/Type Index and embellished with the builtin types, so that you'd find float (builtin), string (builtin), dict (builtin), etc. in the appropriate alphabetical positions. +1 Yeah, I'd love to see something like this. My preference would actually to be to leave the Global Module Index the same and add a Builtin Type Index along the lines of the module index. One of my current problems with the documentation is that, for builtin types, the constructor is found in Built-in Functions[1], but the methods are found in some subsection of Built-in Types[2]. Additionally, the Built-in Types[2] section mixes protocols like the Sequence, Iterator and Mapping protocols with the methods of some of the builtin types that implement these protocols. Here's what I'd like to see happen: (1) Restructure the Built-In Objects[3] section to split Built-in Types into Built-in Protocols and Built-in Types. Built-in Protocols would describe: * the Numeric Procotol (__add__, __sub__, __mul__, etc.) * the Iterator Protocol (__iter__, next, etc.) * the Sequence Protocol (__len__, __getitem__, __iter__, etc.) * the Mapping Protocol (__len__, __getitem__, __iter__, etc.) * the File Protocol (read, write, close, etc.) * the Set Protocol (__len__, __contains__, etc.) and possibly * the String Protocol (Sequence Protocol + upper, lower, etc.) Built-in Types would describe the types that implement the above Protocols, i.e.: * bool (Numeric) * complex (Numeric) * dict (Mapping) * file (File, Iterator) * float (Numeric) * frozenset (Set) * function -- link to description of functions * int (Numeric) * list (Sequence) * long (Numeric) * object -- link to description of classes * set (Set) * str (Sequence) * tuple (Sequence) * type -- link to description of classes * unicode (Sequence) * xrange (Sequence) Not sure if I got them all, but that should be close. Probably this section should also contain all the types listed in Other Built-in Types[4] (2) Fill in each new Built-in Type section with: * the constructor documentation (from Built-in Functions[1]) * links to each Protocol that the type implements * descriptions of partial implementations of Protocols (e.g. tuple is an immutable Sequence) * any additional methods of the type that are not part of a protocol (3) Add a separate page like Global Module Index[4] called Built-in Type Index that links to the sections of the new Built-in Types. IMVHO, this would make finding docs about the builtins much easier. However, this is a fairly large change. A simpler change that would probably get 60-70% of the benefit, would be to just create the Built-in Type Index page, and link to the current page describing that built-in type's Protocol. It might be a little confusing to click on a link that said str type and end up at the Sequence Types page, but I think people could get over it if the more comprehensive solution isn't acceptable. STeVe [1] http://docs.python.org/lib/built-in-funcs.html [2] http://docs.python.org/lib/types.html [3] http://docs.python.org/lib/builtin.html [4] http://docs.python.org/lib/typesother.html [5] http://docs.python.org/modindex.html -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Terry Hancock wrote: *But you do have to remember that strings are documented under sequences this is probably my biggest complaint about the Library Reference --- something as important as string methods should have its own heading in the top-level outline. But that's a nitpick, of course. I'd agree. My one complaint about the documentation, if I had one, would be that the organizational structure is non-intuitive. (Why are dictionaries/lists/strings part of the 'library'?) But once you get the organization down, I have few complaints. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Steven Bethard wrote:
Skip Montanaro wrote:
Mike Given that Python hides the difference between user-defined
Mike objects and built-in objects, it's not clear to me that anything
Mike other than the current system, with all the classes/types in one
Mike place, makes sense.
Maybe the Module Index should be renamed Module/Type Index and embellished
with the builtin types, so that you'd find float (builtin), string
(builtin), dict (builtin), etc. in the appropriate alphabetical
positions.
+1
Yeah, I'd love to see something like this. My preference would actually
to be to leave the Global Module Index the same and add a Builtin
Type Index along the lines of the module index.
One of my current problems with the documentation is that, for builtin
types, the constructor is found in Built-in Functions[1], but the
methods are found in some subsection of Built-in Types[2].
Additionally, the Built-in Types[2] section mixes protocols like the
Sequence, Iterator and Mapping protocols with the methods of some of the
builtin types that implement these protocols.
The two manuals on my book shelf that are the most worn are Alex
Martelli's Python in a Nutshell, (A 2.5 version would be really nice..
hint to Alex), and a C pocket reference. Both are organized by
*subject* and not by library/include.
What I would like to see is something like the following for each item:
0. reference @ sequence code
2. Builtin | import library
3. Type/class: Name/Syntax
4. Description with examples
6. Links to other references of this item in docs
7. Links to related functions or objects in same doc type
8. Keywords
In this way, each item can be a complete entry in a data base that can
be sorted in different ways. Alphabetical, by subject, by library, etc...
The quick reference guide description should mirror the doc strings.
Short but sweet if possible. Any changes to one should be made to the other.
An advanced technical language manual would also be nice for both those
who are interested, and to record implementing details. To start it
could just be any current technical details that do not fit well in the
other categories.
So summing up:
+ Each item/object in a database in a consistent way.
+ Four main categories: Tutor, Quick Ref, Full Ref, and Technical Ref.
+ Cross reference links in each item.
+ Dependency, ie... from library import name listed with each item.
+ keywords enabling look up and searches by subject
As it's been pointed out several times, most of this is already there.
The hard part, and it may not be as hard as I think, is generating the
web pages from this in a nice way, and to create a good search interface
that can create a list of links by a chosen reference selection.
The rest of this is a matter of presentation and details. Which I think
can be worked out, and done to be very similar to the existing pages.
Example from Python Docs:
4.1.3 String functions
The following functions are available to operate on string and Unicode
objects. They are not available as string methods.
capwords( s)
Split the argument into words using split(), capitalize each word
using capitalize(), and join the capitalized words using join(). Note
that this replaces runs of whitespace characters by a single space, and
removes leading and trailing whitespace.
maketrans( from, to)
Return a translation table suitable for passing to translate() or
regex.compile(), that will map each character in from into the character
at the same position in to; from and to must have the same length.
Warning: Don't use strings derived from lowercase and uppercase as
arguments; in some locales, these don't have the same length. For case
conversions, always use lower() and upper().
Could become something like:
Python Quick Ref: 4.1.3.1
import string
Function: capwords(s) - string
Returns a copy of string s with the first letter of each word capitalized.
S = string.capwords(a lowercase string)
Also see capwords: |tutor|full_docs|tech_docs|
Related to: |string.swapcase|string.title|string.capitalize|
Keywords: |standard library|string module|function|string|capital
Python Quick Ref: 4.1.3.2
import string
Function: maketrans(from, to) - table
Return a translation table suitable for passing to translate() or
regex.compile(), that will map each character in from into the
character at the same position in to; from and to must have the
same length.
table = maketrans('abcdefg', 'ABCDEFG')
Also see maketrans: |tutor|full_docs|tech_docs|
Related to:|regex.compile|string.translate||string.strip|string.replace|
Keywords: |standard library|string module|function|string|change
Note that each individual record is complete and stands alone, with
links to a few other relavant items. The keywords allow for some nice
search results. The notes left off would be in the full docs reference.
(They would be included in the quick ref if they
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote: Hi All-- The Python docs are not ideal. I can never remember, for instance, where to find string methods (not methods in the string module, but methods with '') Curiously I had the same problem just the other day, except with list instead of string. I think the problem is that the sections on the actual built-in types (list, str, dict, etc.) are one level too far down to appear in the table of contents of the Library Reference. If things could be rearranged so that their names actually appeared in the table of contents, I think it would make a big difference in this area. -- Greg Ewing, Computer Science Dept, University of Canterbury, Christchurch, New Zealand http://www.cosc.canterbury.ac.nz/~greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ron Adam wrote: What I would like to see is something like the following for each item: 0. reference @ sequence code 2. Builtin | import library 3. Type/class: Name/Syntax 4. Description with examples 6. Links to other references of this item in docs 7. Links to related functions or objects in same doc type 8. Keywords I'm unclear from your description. What constitutes an item? Only functions? Or are types and modules items too? One of the original complaints was that the page for string methods wasn't easily accessible. How does this address that problem? I guess you could search for all records with Type: str. Would the constructor for str show up this way? STeVe -- http://mail.python.org/mailman/listinfo/python-list
Python Documentation (should be better?)
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? -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: ...blah blah blah... Heh, silly me...there is already a huge thread about this...kinda. The intricacies of the computing term greedy aside, yes I think the Python documentation should generally be better. What that means, I have no idea. All I know is that I like PHP's documentation and it should be like that. My question is, why is PHP's documentation so good and Python's mediocre? Does it have to do with corporate backing (I have no idea if PHP is or not, I'm just saying)? The quality/quantity of volunteers? The design of the language itself? -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
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... -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: [...] 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()? 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 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: 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. [snip] What do yall think? I have to say, I don't really have your troubles with the documentation, and I hardly ever use dir() in the interactive shell. You mention only referring to the tutorial. Why don't you check the Language Reference[1] or Library Reference[2]? That said, if you see spots where the documentation needs help, the right answer is to file a feature request[3] to add documentation. If you're feeling especially helpful, providing the documentation you'd like to be added would be greatly appreciated. Python's a community effort -- if you see weak points, you can help the community build a better Python by taking the time to address them yourself. STeVe [1]http://docs.python.org/ref/ref.html [2]http://docs.python.org/lib/lib.html [3]http://sourceforge.net/tracker/?group_id=5470atid=355470 -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
[EMAIL PROTECTED] wrote: 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. I guess I mean Python needs a manual, which is basically what the tutorial serves as, but its not comprehensive and organized like how (I think) a manual should be. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Steven Bethard wrote: Christopher J. Bottaro wrote: 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. [snip] What do yall think? I have to say, I don't really have your troubles with the documentation, and I hardly ever use dir() in the interactive shell. You mention only referring to the tutorial. Why don't you check the Language Reference[1] or Library Reference[2]? Cuz I think the Language Reference is really more of a grammer reference and far too technical to look up simple things like how to declare a function. I guess what I'm trying to say is that there is no manual (for the language itself, not the modules). There is just the tutorial that serves as the manual. I think it should evolve into a manual that is more comprehensive and organized more like other programming manuals (chapter on control structures, functions, classes, inheritance, etc). Kinda funny...I was going to use the email module as an example of a module that lacks examples...but apparently that has been updated since when I last used it...=) That said, if you see spots where the documentation needs help, the right answer is to file a feature request[3] to add documentation. If you're feeling especially helpful, providing the documentation you'd like to be added would be greatly appreciated. Python's a community effort -- if you see weak points, you can help the community build a better Python by taking the time to address them yourself. That true, but to be perfectly honest...I don't feel qualified. I'm still a young'un in this programming game. I'm sure a lot of seasoned devs would scoff at the documentation I write. STeVe -- C [1]http://docs.python.org/ref/ref.html [2]http://docs.python.org/lib/lib.html [3]http://sourceforge.net/tracker/?group_id=5470atid=355470 -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: Christopher J. Bottaro wrote: ...blah blah blah... Heh, silly me...there is already a huge thread about this...kinda. The intricacies of the computing term greedy aside, yes I think the Python documentation should generally be better. What that means, I have no idea. All I know is that I like PHP's documentation and it should be like that. My question is, why is PHP's documentation so good and Python's mediocre? Because PHP is such a 'thrown together' and 'bolted-on' language. If it didn't have *outstanding* documentation (which it does BTW), no one could even begin to understand how they got from a little HTML language to a kinda/sorta OO language. PHP is showing its age... thanks to its docs, it's still *extremely* useful. -- http://mail.python.org/mailman/listinfo/python-list
RE: Python Documentation (should be better?)
I agree. The PHP manual is really good, especially the examples and user contributed notes. I think that's why we need the reference manual most time. It help you to get started on that particular function as well as hint you the trick and trap. I really wish Python manual gets better on these two areas. Is it feasible to write a program to search the mailing list for example and discussion related to particular function and archive it right under the session of the manual. Anyone want to start this project? Maybe a mailing list or forum people can contribute example and notes? Just a thought. Jue -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] Behalf Of Christopher J. Bottaro Sent: Wednesday, May 11, 2005 11:51 AM To: python-list@python.org Subject: Python Documentation (should be better?) 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? -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Manual == scope of the *Lib Reference* + informal style of the *Tutorial*, Right ? Consider non-official manuals such as: + http://diveintopython.org/toc/index.html (free) + python in a nutshell + python cookbook + etc. Cheers, SB -- http://mail.python.org/mailman/listinfo/python-list
RE: Python Documentation (should be better?)
Jue Maybe a mailing list or forum people can contribute example and Jue notes? Contributions can be made at the SourceForge patch tracker: http://sourceforge.net/tracker/?group_id=5470atid=305470 Plain text is fine. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: I think it should evolve into a manual that is more comprehensive and organized more like other programming manuals (chapter on control structures, http://docs.python.org/tut/node6.html or http://docs.python.org/ref/compound.html functions, http://docs.python.org/tut/node6.html#SECTION00660 http://docs.python.org/tut/node6.html#SECTION00670 or http://docs.python.org/ref/function.html classes, inheritance, etc http://docs.python.org/tut/node11.html or http://docs.python.org/ref/class.html Note that the first examples above are from the tutorial, the second form the language reference. Personally, I would think that for 99% of users, going through the tutorial should be sufficient (it was for me). I only use the language reference when I need to explain a particular detail of why Python does something. Was there something that wasn't in the tutorial that you would have liked to be? The more specific you can get, the more easily we can improve the documentation. That said, if you see spots where the documentation needs help, the right answer is to file a feature request[3] to add documentation. If you're feeling especially helpful, providing the documentation you'd like to be added would be greatly appreciated. Python's a community effort -- if you see weak points, you can help the community build a better Python by taking the time to address them yourself. That true, but to be perfectly honest...I don't feel qualified. I'm still a young'un in this programming game. I'm sure a lot of seasoned devs would scoff at the documentation I write. Well then at least file a feature request and indicate what was missing from the documentation, or what part of it confused you. Even if you throw in a few phrases of documentation that never get used, at least they might give the dev who updates the documentation a better idea of the problem you encountered. STeVe -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Le Wed, 11 May 2005 15:58:04 -0400, rbt a écrit : Christopher J. Bottaro wrote: Because PHP is such a 'thrown together' and 'bolted-on' language. If it didn't have *outstanding* documentation (which it does BTW), no one could even begin to understand how they got from a little HTML language to a kinda/sorta OO language. +1 QOTW -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Hi All-- The Python docs are not ideal. I can never remember, for instance, where to find string methods (not methods in the string module, but methods with ''), but I can remember a tortured path to get me there (yes, I know, fix my brain; easier said than done). The module index is good, if what you're looking for is in a module. The tutorial is good. I can usually end up where I want to be by picking up my copy of _Python in a Nutshell_. 95% of the time I can find what I want in there or from there. The other 5% is too new, in the _Python Cookbook_ or in a third-party module/lib. Or it's what I'm trying to write;-) Metta, Ivan -- Ivan Van Laningham God N Locomotive Works http://www.andi-holmes.com/ http://www.foretec.com/python/workshops/1998-11/proceedings.html Army Signal Corps: Cu Chi, Class of '70 Author: Teach Yourself Python in 24 Hours -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: [...] Cuz I think the Language Reference is really more of a grammer reference and far too technical to look up simple things like how to declare a function. I guess what I'm trying to say is that there is no manual (for the language itself, not the modules). There is just the tutorial that serves as the manual. I think it should evolve into a manual that is more comprehensive and organized more like other programming manuals (chapter on control structures, functions, classes, inheritance, etc). Fair enough. An 'upgraded' tutorial that would include simple discussion on some 'advanced topics' could be helpful. For example, there is (almost) no reference to the new-style classes inside the tutorial, the yield keyword and generator stuff is described in half a page, etc. SB -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
I can usually end up where I want to be by picking up my copy of _Python in a Nutshell_. 95% of the time I can find what I want in there or from there. This book is really great. Could anybody convince Alex Martelli to basically make it freely available to the world ? 0.9 wink. I would gladly pay the price of the book to make it free ! ... just dreamin' ... SB -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
I don't know what you guys are talking about!! In idle: help(module) I love the way python handles documentation. Its not invansive -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Cuz I think the Language Reference is really more of a grammer reference and far too technical to look up simple things like how to declare a function. I guess what I'm trying to say is that there is no manual (for the language itself, not the modules). There is just the tutorial that serves as the manual. I think it should evolve into a manual that is more comprehensive and organized more like other programming manuals (chapter on control structures, functions, classes, inheritance, etc). If what you miss mostly is a quick way to look up language features, modules and APIs, the python quick reference is an excellent starting point, especially for someone new to the language: http://rgruet.free.fr/PQR24/PQR2.4.html (also linked from http://www.python.org/doc/ along with other doc sources). It's available in pdf as well. George -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote: The Python docs are not ideal. I can never remember, for instance, where to find string methods (not methods in the string module, but methods with '') Hmmm... Well going to http://docs.python.org/ and typing string methods into the search box gives, as the first hit: http://docs.python.org/lib/string-methods.html Even if you just search for string, that URL is the second hit, and pretty clearly the right one from the title. STeVe -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
rbt wrote: Christopher J. Bottaro wrote: Christopher J. Bottaro wrote: ...blah blah blah... Heh, silly me...there is already a huge thread about this...kinda. The intricacies of the computing term greedy aside, yes I think the Python documentation should generally be better. What that means, I have no idea. All I know is that I like PHP's documentation and it should be like that. My question is, why is PHP's documentation so good and Python's mediocre? Because PHP is such a 'thrown together' and 'bolted-on' language. If it didn't have *outstanding* documentation (which it does BTW), no one could even begin to understand how they got from a little HTML language to a kinda/sorta OO language. PHP is showing its age... thanks to its docs, it's still *extremely* useful. Exactly!! See thats what I'm saying. I _think_ its widely accepted that PHP has awesome documentation. And like rbt said, that makes it extremely useful. Why can't Python have documentation like that? The language is awesome, it just needs documentation of the same quality. I'm sorry that I have such a hard time giving specific examples and what not. All I can do (as of now) is kinda report the vibe I get...which is completely useless, I know...=) -- C -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: Contrast that with Python. First off there is no search mechanism built into the documentation page (yes I know you can google it, but that just doesn't feel right). Um, are you looking at the current documentation page? http://docs.python.org/ In the upper right hand corner, I see a box entitled Search: and a button that says submit. STeVe -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham a écrit :
Hi All--
The Python docs are not ideal. I can never remember, for instance,
where to find string methods (not methods in the string module, but
methods with ''),
dir('')
['__add__', '__class__', '__contains__', '__delattr__', '__doc__',
'__eq__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__',
'__getslice__', '__gt__', '__hash__', '__init__', '__le__', '__len__',
'__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__',
'__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__',
'__str__', 'capitalize', 'center', 'count', 'decode', 'encode',
'endswith', 'expandtabs', 'find', 'index', 'isalnum', 'isalpha',
'isdigit', 'islower', 'isspace', 'istitle', 'isupper', 'join', 'ljust',
'lower', 'lstrip', 'replace', 'rfind', 'rindex', 'rjust', 'rstrip',
'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title',
'translate', 'upper', 'zfill']
HTH
--
http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Bruno Desthuilliers wrote:
Ivan Van Laningham a écrit :
Hi All--
The Python docs are not ideal. I can never remember, for instance,
where to find string methods (not methods in the string module, but
methods with ''),
dir('')
['__add__', '__class__', '__contains__', '__delattr__', '__doc__',
'__eq__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__',
'__getslice__', '__gt__', '__hash__', '__init__', '__le__', '__len__',
'__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__',
'__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__',
'__str__', 'capitalize', 'center', 'count', 'decode', 'encode',
'endswith', 'expandtabs', 'find', 'index', 'isalnum', 'isalpha',
'isdigit', 'islower', 'isspace', 'istitle', 'isupper', 'join', 'ljust',
'lower', 'lstrip', 'replace', 'rfind', 'rindex', 'rjust', 'rstrip',
'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title',
'translate', 'upper', 'zfill']
Probably more useful:
py help(str)
Help on class str in module __builtin__:
class str(basestring)
| str(object) - string
|
| Return a nice string representation of the object.
| If the argument is a string, the return value is the same object.
|
...
|
| capitalize(...)
| S.capitalize() - string
|
| Return a copy of the string S with only its first character
| capitalized.
|
| center(...)
| S.center(width[, fillchar]) - string
|
| Return S centered in a string of length width. Padding is
| done using the specified fill character (default is a space)
|
...
|
| upper(...)
| S.upper() - string
|
| Return a copy of the string S converted to uppercase.
|
| zfill(...)
| S.zfill(width) - string
|
| Pad a numeric string S with zeros on the left, to fill a field
| of the specified width. The string S is never truncated.
...
STeVe
--
http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Shi, Jue wrote: I agree. The PHP manual is really good, especially the examples and user contributed notes. Dunno if anyone's spent much time editing this, but a while a go AMK posted: http://www.amk.ca/diary/archives/cat_python.html#003336 which puts a wiki side-by-side with the Python docs: http://pydoc.amk.ca/frame.html STeVe -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Hi All--
Yes. There are multiple ways I can correct myself, some, I'm sure,
involving chains and whips. But you're all missing the point:
Christopher is right! Python docs are not as good as PHP docs. Why
not? Why do I have to be told Hey, there are fifty ways to get what
you want! when I should be able to go to the main doc page and SEE the
right link to click. Why isn't there a Methods in Standard Objects
page, for instance? Why would I have to search?
And the search is sucky, anyway. So there;-) Christopher described the
right way. I should be able to type string methods into the text box,
push submit, and IT SHOULD HAND ME THE PAGE. Not Results 1 - 20 of
about 9,800 from www.python.org for string methods. (0.78 seconds) (and
no, I am not exaggerating). And the first hit is from Python 2.1.3, NOT
the current doc. Sorry. No cigar.
There's Only One Way to Do It, except in the Docs, that is. Good as
Google is, it is not good for a doc search. We don't have a doc search,
we have a doc hurl.
BTW, my tortured method is quicker than Bruno's, because to use his
method I'd have to start the interactive interpreter.
Bruno Desthuilliers wrote:
Ivan Van Laningham a écrit :
Hi All--
The Python docs are not ideal. I can never remember, for instance,
where to find string methods (not methods in the string module, but
methods with ''),
dir('')
Metta,
Ivan
--
Ivan Van Laningham
God N Locomotive Works
http://www.andi-holmes.com/
http://www.foretec.com/python/workshops/1998-11/proceedings.html
Army Signal Corps: Cu Chi, Class of '70
Author: Teach Yourself Python in 24 Hours
--
http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher J. Bottaro wrote: Why can't Python have documentation like that? The language is awesome, it just needs documentation of the same quality. The canonical answer is, roughly, 'it can'. A standard addendum is to say that contributions are always welcome. A common clarification of that is to point out that in open source projects, somebody has to volunteer to do the work, or somebody has to be willing to pay for it to be done. Which are you? Personally, I have little problem with Python's docs, so I'm certainly going to focus my negligible free time elsewhere. (Like rambling on and on answering newsgroup postings. :-) If you felt strongly enough about the negative aspects of Python's docs, you would be looking for places where you could make a contribution. (Lack of experience is not only not an excuse, but is probably an excellent qualification for the job!) -Peter -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Sébastien Boisgérault [EMAIL PROTECTED] wrote in message news:[EMAIL PROTECTED] Manual == scope of the *Lib Reference* + informal style of the *Tutorial*, You, as well as the OP, left out the Language Reference, which is the manual (by me definition) for the language itself. Chapter 2 of the Lib Reference on builtin types and functions is essential also and should be read in its entirety. The rest, to me, is 'need to know' reading, especially since the addition of string methods. Consider non-official manuals such as: + http://diveintopython.org/toc/index.html (free) + python in a nutshell + python cookbook + etc. Yes, these and others (the etc) are helpful too, and should not be discounted just because they are maintained independently of the core developer group. Terry J. Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan and Company: Keep this in your favorites bar: http://rgruet.free.fr/PQR24/PQR2.4.html Under Contents, click on Basic types and their operations:...string But I think this could have an expanded idioms section. I.E. for index,element in enumarate(alist): or for atup in zip(list1,list2): Maybe we could compile a list? Maybe under Idioms (was Re: Python Documentation)? Anybody care to send in their favorites? I'll compile them. James On Wednesday 11 May 2005 04:38 pm, Ivan Van Laningham wrote: Hi All-- [rant] -- James Stroud UCLA-DOE Institute for Genomics and Proteomics Box 951570 Los Angeles, CA 90095 http://www.jamesstroud.com/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Hi All-- Steven Bethard wrote: Ivan Van Laningham wrote: I should be able to type string methods into the text box, push submit, and IT SHOULD HAND ME THE PAGE. Not Results 1 - 20 of about 9,800 from www.python.org for string methods. (0.78 seconds) Regardless, assuming the right link is the first one, do I understand your complaint correctly as saying that you want Python to automatically pick the first link for you? Do others agree with this complaint? I imagine it wouldn't be that hard to add the equivalent of Google's I'm Feeling Lucky button beside the submit button if that would really help. No. If I type string methods into the search box (OK, I will type the quotes), how many pages can there be? If there are two or more, give me the choice; if there is one, take me to it. Why are there 9,801 pages containing string, or method, or both, or neither? What's wrong with this picture? http://docs.python.org/lib/string-methods.html In fact, I tried just string and couldn't find anything but the current docs in the first 10 pages (and was too lazy to check anything else). Could you tell me how to reproduce your results (of getting Python 2.1.3)? http://www.python.org/doc/ Type string methods into the box; push submit. Result: Results 1 - 20 of about 9,800 from www.python.org for string methods. (0.14 seconds) I did not go to docs.python.org, I went to www.python.org and clicked on the doc link. There is a difference, clearly, but I maintain there should not be. If I click on Documentation on the main page, am I asking for All possible old and new and broken and repaired and intermediate documentation pages? No, I kind of thought I was asking for the latest documentation. I tried string methods at docs.python.org, and got Results 1 - 20 of about 455 from docs.python.org for string methods. (0.11 seconds); string methods retrieved Results 1 - 10 of about 30 from docs.python.org for string methods. (0.13 seconds). Why the difference? Metta, i-have-not-yet-begun-to-rant-ly y'rs, Ivan Sorry I am out of room for smiley faces -- Ivan Van Laningham God N Locomotive Works http://www.pauahtun.org/ http://www.foretec.com/python/workshops/1998-11/proceedings.html Army Signal Corps: Cu Chi, Class of '70 Author: Teach Yourself Python in 24 Hours -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote: http://www.python.org/doc/ Type string methods into the box; push submit. Result: Results 1 - 20 of about 9,800 from www.python.org for string methods. (0.14 seconds) I did not go to docs.python.org, I went to www.python.org and clicked on the doc link. There is a difference, clearly, but I maintain there should not be. If I click on Documentation on the main page, am I asking for All possible old and new and broken and repaired and intermediate documentation pages? No, I kind of thought I was asking for the latest documentation. I tried string methods at docs.python.org, and got Results 1 - 20 of about 455 from docs.python.org for string methods. (0.11 seconds); string methods retrieved Results 1 - 10 of about 30 from docs.python.org for string methods. (0.13 seconds). Why the difference? Searching on docs.python.org goes through just the stuff that's on docs.python.org, which is pretty much just documentation. Google's magic points to the current documentation. Searching on www.python.org trolls through the entire www.python.org site. The search box doesn't narrow its scope just because you happen to be in the Documentation section currently. It doesn't get the current documentation because Google's magic gets a bit confused. -- Robert Kern [EMAIL PROTECTED] In the fields of hell where the grass grows high Are the graves of dreams allowed to die. -- Richard Harter -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote: Python docs are not as good as PHP docs. Oh my. I hope you are just making that up. PHP documentation is guesstimated on how PHP works on average. Add the online comments clutter and you probably are better off reading the source. -- John MexIT: http://johnbokma.com/mexit/ personal page: http://johnbokma.com/ Experienced programmer available: http://castleamber.com/ Happy Customers: http://castleamber.com/testimonials.html -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Christopher Exactly!! See thats what I'm saying. I _think_ its widely Christopher accepted that PHP has awesome documentation. And like rbt Christopher said, that makes it extremely useful. Why can't Python Christopher have documentation like that? It's just a simple matter of writing, editing, proofreading, feedback, etc. Given the current documentation set, does it appear what you're looking for is mostly a reorganization of the existing content? You gave the example of searching for array. That happens to return something very useful because it maps directly to a section of the PHP manual. I tried searching for float and string but got much less on-target responses. When I searched for a term and selected selected the online documentation search category it did a Google search, which is what the search box on docs.python.org does. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Steve [AMK's] wiki side-by-side with the Python docs: Steve http://pydoc.amk.ca/frame.html There's also wikalong, though that's firefox-specific. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Hi All-- Robert Kern wrote: Ivan Van Laningham wrote: http://www.python.org/doc/ Searching on docs.python.org goes through just the stuff that's on docs.python.org, which is pretty much just documentation. Google's magic points to the current documentation. Searching on www.python.org trolls through the entire www.python.org site. The search box doesn't narrow its scope just because you happen to be in the Documentation section currently. It doesn't get the current documentation because Google's magic gets a bit confused. I get that. My question, cleverly concealed in a rant, was, Why does clicking on the Documentation link at python.org NOT take me to docs.python.org? Why is there a difference? If there must be a difference, why isn't the difference labelled as such? This is a difference that makes a difference. Metta, Ivan -- Ivan Van Laningham God N Locomotive Works http://www.pauahtun.org/ http://www.foretec.com/python/workshops/1998-11/proceedings.html Army Signal Corps: Cu Chi, Class of '70 Author: Teach Yourself Python in 24 Hours -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Hi All-- John Bokma wrote: Ivan Van Laningham wrote: Python docs are not as good as PHP docs. Oh my. I hope you are just making that up. PHP documentation is guesstimated on how PHP works on average. Add the online comments clutter and you probably are better off reading the source. I didn't write that; I was riffing on Christopher's contention that Python's docs ought to be awesome, which I think ought to be true. Metta, Ivan -- Ivan Van Laningham God N Locomotive Works http://www.andi-holmes.com/ http://www.foretec.com/python/workshops/1998-11/proceedings.html Army Signal Corps: Cu Chi, Class of '70 Author: Teach Yourself Python in 24 Hours -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Ivan Van Laningham wrote: Hi All-- Robert Kern wrote: Ivan Van Laningham wrote: http://www.python.org/doc/ Searching on docs.python.org goes through just the stuff that's on docs.python.org, which is pretty much just documentation. Google's magic points to the current documentation. Searching on www.python.org trolls through the entire www.python.org site. The search box doesn't narrow its scope just because you happen to be in the Documentation section currently. It doesn't get the current documentation because Google's magic gets a bit confused. I get that. My question, cleverly concealed in a rant, was, Why does clicking on the Documentation link at python.org NOT take me to docs.python.org? Why is there a difference? If there must be a difference, why isn't the difference labelled as such? This is a difference that makes a difference. I believe that docs.python.org was added mostly to aid Google searches. I *do* think that the Documentation link should go to docs.python.org. I believe there is a mailing list somewhere that discusses improvements to the website. Googles Ah: http://mail.python.org/mailman/listinfo/pydotorg/ -- Robert Kern [EMAIL PROTECTED] In the fields of hell where the grass grows high Are the graves of dreams allowed to die. -- Richard Harter -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
On Wednesday 11 May 2005 02:54 pm, Christopher J. Bottaro wrote: I guess what I'm trying to say is that there is no manual (for the language itself, not the modules). There is just the tutorial that serves as the manual. I think it should evolve into a manual that is more comprehensive and organized more like other programming manuals (chapter on control structures, functions, classes, inheritance, etc). That's probably because 1) The language itself is extremely simple. What you really need is in the tutorial (or in several books including Learning Python from O'Reilly which I learned from). If you need more than that, then you must be looking for something fairly picky (like magic methods perhaps), so you really do want to be reading the Language Reference. Don't overthink it. 2) About 90% of what you want to do in Python is done by using a library module. Furthermore, it's the 90% you are likely to forget, thus needing a manual for reference. That's why I regard the Library Reference as the manual. Don't forget that many built-ins are documented here as well (e.g. the methods of strings*). There are, of course, numerous introductions to Python which can be freely downloaded, and several commercial books on the subject. IMHO, the manual is to be the ultimate, most up-to-date, most accurate, and most detailed source on the language (you go there to check details if something doesn't work the way your tutorial says it does). Readability is secondary --- use a third party source for the friendly version (not that the Language or Library References are unfriendly --- they're just concise, IMHO). Also, Python gives you something most languages don't --- the interactive interpreter allows you to play around with Python constructs and find out how any picky details work by trying it out. This is clearly the most guaranteed accurate way to find out the answer to a syntax or semantic problem, and it's so easy it's hard to justify the wasted time perusing a manual for such details. That's why people are frequently recommended to ask the interpreter about such details. This saves a HUGE amount of time for me --- I'm surprised that you dislike this approach, it seems extremely practical to me. *But you do have to remember that strings are documented under sequences this is probably my biggest complaint about the Library Reference --- something as important as string methods should have its own heading in the top-level outline. But that's a nitpick, of course. -- Terry Hancock ( hancock at anansispaceworks.com ) Anansi Spaceworks http://www.anansispaceworks.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
On Wednesday 11 May 2005 03:42 pm, flamesrock wrote: I don't know what you guys are talking about!! In idle: help(module) I love the way python handles documentation. Its not invansive Yeah, and if you write your docstrings with reasonable care it works for your own modules, too! I love that. ISTM, that Python is the best Literate Programming language yet available (much easier than cweb and whatnot that gave us the term). -- Terry Hancock ( hancock at anansispaceworks.com ) Anansi Spaceworks http://www.anansispaceworks.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation (should be better?)
Aahz wrote: In article [EMAIL PROTECTED], Robert Kern [EMAIL PROTECTED] wrote: I believe that docs.python.org was added mostly to aid Google searches. I *do* think that the Documentation link should go to docs.python.org. I believe there is a mailing list somewhere that discusses improvements to the website. Googles Ah: http://mail.python.org/mailman/listinfo/pydotorg/ Google gave you the wrong answer. ;-) pydotorg is for people actively working on the website, not for discussions about improving the website. There's another list for that, but it's currently moribund because we're waiting for a website redesign. (The PSF board voted to pay someone to redesign www.python.org.) Dammit! Google's supposed to read my mind and give me what I want, not what I ask for! -- Robert Kern [EMAIL PROTECTED] In the fields of hell where the grass grows high Are the graves of dreams allowed to die. -- Richard Harter -- http://mail.python.org/mailman/listinfo/python-list
