[Python-Dev] New Pythondoc by effbot (original) (raw)

Guido van Rossum guido at python.org
Sun Jan 22 00:20:26 CET 2006

On 1/21/06, Georg Brandl <g.brandl-nospam at gmx.net> wrote:

What Fredrik hacks together there (http://www.effbot.org/lib) is very impressive. I especially like the "permalinks" in this style:

http://effbot.org/lib/os.path.join

Which (despite having "perma" in its name) evaporates and leaves behind a link to os.path.html#join.

What I would suggest (for any new doc system) is a "split" view: on the left, the normal text, on the right, an area with only the headings, functions, example and "see also" links (which preferably stays in sight). This way, you always keep the outline in view.

Can you mock that up a bit? I'm somewhat confused about what you're requesting, and also worried that it would take up too much horizontal space. (Despite that monitors are wider than tall, horizontal real estate feels more scarce than vertical, because horizontal scrolling is such a pain.)

Of course, I wouldn't say no to a user-commenting system, but this would have to be moderated.

Why? If wikipedia can do without moderation (for most pages) then why couldn't the Python docs?

What I'm also curious about regarding the current docs, why are optional arguments in function declarations not written in Python style?

I'm assuming you're asking why we use

foo(a[, b[, c]])

instead of

foo(a, b=1, c=2)

? I can see several reasons; arguments with default values aren't necessarily usable keyword arguments (at least not if they function/method is implemented in C); the default value isn't always relevant (or is dynamic, or is a huge expression); and square brackets are the standard way in computer manuals to indicate optional parts of syntax.

-- --Guido van Rossum (home page: http://www.python.org/~guido/)

More information about the Python-Dev mailing list