Python Documentation (should be better?)

[Ron Adam]

Steven Bethard wrote:

> 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?

No, not only functions. Types, objects, methods, libraries, even 
packages.  The sequence code is what defines the tree.  It still works 
with other more abstract objects such as "Introduction", "Operators", 
"Notes on ___".  Some fields wouldn't be used in those cases.

The type/syntax field for general documents items, might be 
<instructional>, or <informational> or some other descriptive term.  The 
"keywords" themselves could also be records with definitions of what 
they are.  They would probably be under the 'Introduction/What is 
python' section of the docs and list what things are strings for example.


> 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

Let's see:  ( The quick_ref for str could have something like. )

"""
Python Quick Ref: n.n.n.n
__Builtin__
<type 'type'> str(object) -> string

Return a nice string representation of the object.
If the argument is a string, the return value is the same object.

s = str(123.456)
s = str([1,2,3])

Also see str: |tutor|full_docs|tech_docs|
Related to: |builtin.types|float|bool|int|long|
Keywords: |builtin|types|string|
"""

So from here you would click on the |full_docs| link and get a more 
complete description with all of the str's methods listed. Clicking on 
the string keyword link would give you an index of everything with the 
string keyword in it, in the quick_ref, (the current), docs.

This format, is based on the C pocket reference I have, it is very 
usable.  It could be printed in alphabetical order and you could find 
things very easily.  An index could be printed by keyword.  That could 
give you a by-subject method of finding things from the printed version.

Of course this wouldn't be something that could be put together over 
night.  And it will more than likely make shortcomings more obvious at 
first.  Holes where stuff should be, but that may be a good thing as 
they can then be fixed.

_Ron