Annotatable Python docs -- now a reality !!!

[Stephen Ferg]

Andrew Kuchling has just posted this (see below) on his blog.

I'm confident that people will use this, if they know it is available.
So now is the time to get the word out. This is something everyone in
the Python community should know about it.

==================================================
from http://www.amk.ca/diary/archives/cat_python.html#003336

September 09, 2004

Annotatable Python docs

In recent months several posters on comp.lang.python have suggested
that Python would benefit from making it possible for people to
comment on the documentation, an approach similar to the PHP docs.
However, no one has ever actually tried to set up such a system.

In a half-hour hack, I wrapped a frameset around the Python 2.3.4
documentation, added some JavaScript that updates another frame to
display a Wiki page for the documentation page you're viewing, and
simplified the Wiki pages as much as I easily could.

The resulting annotatable documentation is at
http://pydoc.amk.ca/frame.html. Please go and add any commentary,
links, or other material you wish. Let's see if commenting on the docs
is a feature people will use, or if it's a feature people just say
they'll use.

 

[Michael Hudson]

Andrew Kuchling has just posted this (see below) on his blog.

He also posted about it here last week!
([email protected]).

Cheers,
mwh

 

[Guyon Morée]

oooow man, i was working on this same thing since I was told: "do it
yourself then!".


but anyway, i had kinda the same idea using javascript to update a frame,
but not in a wiki form...

 

[Fred Pacquier]

He also posted about it here last week!
([email protected]).

Well I, for one, had missed that first annoucement, so thanks to Steve for
the repeat !

I trust it will also appear in the next weekly DrDobbs/Python URL...

 

[A.M. Kuchling]

oooow man, i was working on this same thing since I was told: "do it
yourself then!".
but anyway, i had kinda the same idea using javascript to update a frame,
but not in a wiki form...

You can still help by offering patches to fix bugs in the JavaScript;
various people have pointed out problems in the comments at
http://www.airynothing.com/cgi-bin/mt-comments.cgi?entry_id=3336 .

--amk

 

[Robin Siebler]

So, is there a way to search for annotations? I don't mean any text
in particular, I mean 'show me everything that has been annotated'.

 

[Bob]

Why not convert them to a wiki format? That would be a good and clean way to do it.

 

[Carlos Ribeiro]

Why not convert them to a wiki format? That would be a good and clean way to do it.

In my not-so-humble opinion, the *best* way to solve it would be a
custom Wiki-like implementation, where the docs would stay as they are
(unedited) with comments attached to the text. I have imagined it like
this:

-- add some "anchors" to the documentation, using a visual indicator.
(for example, at the start of every subsection or even paragraph; the
anchor could aligned to the left margin without cluttering the
format).

-- clicking on the anchor allows one to collapse/expand the
annotations for that section.

-- once expanded, it would be possible to write an a new annotation
just by writing it with Wiki-style markup.

To make things complete, the Wiki-style markup would allow for links
to the documentation using a simple syntax; for example,
[[Library/strings]] would point to the documentation chapter for the
strings standard library. This would make navigation pretty easy.

But in retrospect, I think that AMD did the right thing. I could be
talking about it for days to end, but he did implement his version,
and made it available, and that's what count -- actual running code.


--
Carlos Ribeiro
Consultoria em Projetos
blog: http://rascunhosrotos.blogspot.com
blog: http://pythonnotes.blogspot.com
mail: (e-mail address removed)
mail: (e-mail address removed)

 

[Skip Montanaro]

Bob> Why not convert them to a wiki format?

Convert what to a wiki format? Not everyone will have your reference
message available.

Skip