Python Documentation (should be better?)

[Ron Adam]

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 also are in the doc 
string.)

A tutorial link may not be available for everthing, but everything that 
is in the tutorial could have that link included.

Cheer's _Ron