[Doc-SIG] What to do next for 2.6?
g.brandl at gmx.net
Sun Aug 31 22:52:03 CEST 2008
A.M. Kuchling schrieb:
> This weekend I made a final revision pass over the 2.6 "What's New"
> document and am now finished with it (barring any small corrections or
> omissions that come in).
> What should I do now with my Python doc time? Georg, do you have any
> suggestions? I could start reading through one of the manuals from
> end-to-end or go through the bug tracker for doc items. Are there any
> writing-related tasks you've been meaning to do before 2.6final?
There is one thing I've been putting off for quite a long time :)
Basically, the builtin types aren't documented well. The
/library/stdtypes document is too long and not structured in a good
fashion. Also, signatures for the constructors are documented in
/library/functions which is not wrong but not satisfying either.
Also, the type hierarchy in the "data model" section from the lang.
ref. has overlaps with that section. For example, both document some
special methods, both document the built-in types, etc.
I would like to rename the lang. reference to "Core Python language".
This document would then contain the language spec, ideally enhanced with
some examples for those not liking having EBNF thrown into their face,
the "data model" section with all its customization docs, and the content
on built-in functions and types, all special methods and type methods
properly documented etc. (e.g. I think some new float methods aren't
This is a large task, and I don't want to burden it on you. In my opinion
it will make the Python documentation structure easier to grasp. I don't
know how much time you have; I've never found enough of it to start.
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.
More information about the Doc-SIG