By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
440,666 Members | 1,909 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 440,666 IT Pros & Developers. It's quick & easy.

Pythondocs.info : collaborative Python documentation project

P: n/a
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.

Regards,

Nicolas.
-----
http://www.pythondocs.info

Sep 16 '06 #1
Share this Question
Share on Google+
34 Replies


P: n/a
ni*******@gmail.com wrote:
I have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
Where have you read that?

wildemar
Sep 16 '06 #2

P: n/a
ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.
While I am all in favor of improving Python's documentation I am not
sure that fragmenting it in this way is a good idea. Couldn't you
instead devote your efforts to improving the docs at docs.python.org? It
is, after all, an open source project ...

regards
Steve
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC/Ltd http://www.holdenweb.com
Skype: holdenweb http://holdenweb.blogspot.com
Recent Ramblings http://del.icio.us/steve.holden

Sep 16 '06 #3

P: n/a

Wildemar Wildenburger wrote:
ni*******@gmail.com wrote:
I have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
>
Where have you read that?

wildemar
I don't mean to start a flame war about this but here are some
reference of people, who like me, don't like the current python doc:
http://xahlee.org/UnixResource_dir/writ/python_doc.html
http://mail.python.org/pipermail/pyt...ay/280634.html
....
You really can find dozens of such discussions on the net.

I think the PHP documentation is a really good one in comparison.

Nicolas.

Sep 16 '06 #4

P: n/a
On Saturday 16 September 2006 19:16, ni*******@gmail.com wrote:
I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.
I like your enthusiasm but it appears that what you plan is similar to the
Python Quick Reference at http://rgruet.free.fr/

I second that the Python documentation is lacking. There is no software
that is adequately documented anyway. Show me a man page of a Perl module
and it takes me minutes to use it. The same in Python often means Google
to find some examples on how to use a module. Many parts of the standard
library are badly documented IMHO. There is often no way to know how to
use a certain module without looking at its source. But why don't you and
I rather provide patches to the current documentation rather than writing
yet another incomplete resource. IMHO python.org should be completed. And
at least you motivated me to look for ways to contribute to python.org. :)

Cheers
Christoph
Sep 16 '06 #5

P: n/a

ni*******@gmail.com wrote:
Wildemar Wildenburger wrote:
ni*******@gmail.com wrote:
I have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
>
Where have you read that?

wildemar

I don't mean to start a flame war about this but here are some
reference of people, who like me, don't like the current python doc:
http://xahlee.org/UnixResource_dir/writ/python_doc.html
http://mail.python.org/pipermail/pyt...ay/280634.html
\
Please don't use Xah Lee as an example...please.

Robert

Sep 16 '06 #6

P: n/a
On Sat, 16 Sep 2006 10:40:43 -0700, nicolasfr wrote:
>>I have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
Where have you read that?
http://xahlee.org/UnixResource_dir/writ/python_doc.html
http://mail.python.org/pipermail/pyt...ay/280634.html
I think the PHP documentation is a really good one in comparison.
What you should have done first is to suggest to contribute to the
official Python doc.
Then, if you encounter too much dumbs (and only in that case) you could
fork docs.python.org and do your own project.
That's the way free software works.

Sep 16 '06 #7

P: n/a

Christoph Haas wrote:
On Saturday 16 September 2006 19:16, ni*******@gmail.com wrote:
<snip>
>
I second that the Python documentation is lacking. There is no software
that is adequately documented anyway. Show me a man page of a Perl module
and it takes me minutes to use it.
I would say that Perl module documentation is really good. Most of them
have plenty examples on how to use the module itself.

That said...the Python docs are open source. Just start going through
them and adding examples. It shouldn't be too hard and will benefit
everyone who use them.

Robert

Sep 16 '06 #8

P: n/a
ni*******@gmail.com wrote:
I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info
I agree that Python's docs could use improvement, and I love the idea of
using a Wiki for the purpose. But maybe MediaWiki would be a better
choice of software? Dokuwiki's syntax looks foreign and a little bit
intimidating to me, but Wikipedia has made pretty much everyone familiar
with MediaWiki's syntax. Less syntax to learn lowers the cost of entry,
which should lead to more contributors.
Sep 16 '06 #9

P: n/a

Rakotomandimby (R12y) wrote:
What you should have done first is to suggest to contribute to the
official Python doc.
I wrote an email a few months ago to the Python docs support email
address to offer my help but never got any answer.
Then, if you encounter too much dumbs (and only in that case) you could
fork docs.python.org and do your own project.
That's the way free software works.
Everytime I am lookink at how to do this or that in Python I write it
down somewhere on my computer. (For ex. Threading. After reading the
official documentation I was a bit perplex. Hopefully I found an
article an managed to implement threads with only like 20 lines of code
in my script. That should have been in the docs first, not in an
article elsewhere... Same problem for handling gzipped files. I wanted
to know if the file I opened was a gzip archive or not. Not a clue in
the docs...) I have just decided to share all this knowledge this with
other. Community will decide if this wiki is of any interest. If not it
will just remain my personnal notebook for Python tips...

Anyway Python rocks, that's the important point!

Sep 16 '06 #10

P: n/a
Everytime I am lookink at how to do this or that in Python I write it
down somewhere on my computer. (For ex. Threading. After reading the
official documentation I was a bit perplex. Hopefully I found an
article an managed to implement threads with only like 20 lines of code
in my script. That should have been in the docs first, not in an
article elsewhere... Same problem for handling gzipped files. I wanted
to know if the file I opened was a gzip archive or not. Not a clue in
the docs...) I have just decided to share all this knowledge this with
other. Community will decide if this wiki is of any interest. If not it
will just remain my personnal notebook for Python tips...

Anyway Python rocks, that's the important point!
Then how about running your site on python and not php?

Just a thought.
Sep 16 '06 #11

P: n/a
ni*******@gmail.com wrote:
Rakotomandimby (R12y) wrote:
>What you should have done first is to suggest to contribute to the
official Python doc.

I wrote an email a few months ago to the Python docs support email
address to offer my help but never got any answer.
What did that email say?
- "Your docs suck!"? (useless)
- "Your docs aren't the most useful. May I offer to help?" (better, but
somewhat thin. And if the answer had just been "Yes." You'd be no wiser.)
- "Hey, I found this article explaining XY. I made a
tutorial/how-to/documentation-chapter, and here it is. Hope you can use
it." (fantastic/preferred)

http://www.python.org/dev/doc/ has info on how to participate.

Everytime I am lookink at how to do this or that in Python I write it
down somewhere on my computer. (For ex. Threading. After reading the
official documentation I was a bit perplex. Hopefully I found an
article an managed to implement threads with only like 20 lines of code
in my script. That should have been in the docs first, not in an
article elsewhere... Same problem for handling gzipped files. I wanted
to know if the file I opened was a gzip archive or not. Not a clue in
the docs...) I have just decided to share all this knowledge this with
other. Community will decide if this wiki is of any interest. If not it
will just remain my personnal notebook for Python tips...
Let me stress that contributing to the *official* docs is a lot more
rewarding and (I think) sensible. I can't stop you and I appreciate your
enthusiasm. You might however consider helping fix the dam than build
one where no water water runs.

wildemar
Sep 16 '06 #12

P: n/a
I would like to see more than one source.. Not that the documentation
is good or bad it is just that different people may come up with
different ways to explain the same thing and that is good in my view.
I would like to see the re module and the string module with as many
examples as humanly possible to overexplain it for me. (I am currently
downloading a hole directory of re module stuff to try to overcome it)

http://www.dexrow.com


Leif K-Brooks wrote:
ni*******@gmail.com wrote:
I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

I agree that Python's docs could use improvement, and I love the idea of
using a Wiki for the purpose. But maybe MediaWiki would be a better
choice of software? Dokuwiki's syntax looks foreign and a little bit
intimidating to me, but Wikipedia has made pretty much everyone familiar
with MediaWiki's syntax. Less syntax to learn lowers the cost of entry,
which should lead to more contributors.
Sep 16 '06 #13

P: n/a
On Sat, 16 Sep 2006 22:43:41 +0200, Daniel Nogradi wrote:
Then how about running your site on python and not php?
PHP has "better" documentation... ;-)
More seriously, I can provide a CPS hosting to nicolasfr if he wants.
Sep 16 '06 #14

P: n/a
On Sat, 16 Sep 2006 12:30:56 -0700, Robert Hicks wrote:
That said...the Python docs are open source. Just start going through
them and adding examples.
ASPN (activestate) is a good place for examples...
Sep 16 '06 #15

P: n/a
ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info
And what's so wrong about
http://wiki.python.org/moin/ ?

I'm really not trying to put you down, I just feel that the closer the
documentation is to the official website the more people will read it
(or am I being too naive here?).

wildemar
Sep 16 '06 #16

P: n/a
* ni*******@gmail.com (2006-09-16 18:40 +0100)
Wildemar Wildenburger wrote:
>ni*******@gmail.com wrote:
>>I have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
Where have you read that?

wildemar

I don't mean to start a flame war about this but here are some
reference of people, who like me, don't like the current python doc:
http://xahlee.org/UnixResource_dir/writ/python_doc.html
*chuckle* *manic laughter* *cough cough* X L - you really made my
day...

Thorsten
Sep 17 '06 #17

P: n/a
Here is an idea for improving Python official documentation:

Provide a tab-based interface for each entry, with the overview/summary
at the top-level, with a row of tabs underneath:
1. Official documentation, with commentary posted at the bottom
(ala Django documentation)
2. Examples wiki
3. Source code browser with a folding/docstring mode
4. Bugs/To-Do

Of course, building this would take a lot of work, and I'm not offering
to build it myself...I just find that something like this is what I've
been longing for.

Sep 17 '06 #18

P: n/a

ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.

Regards,

Nicolas.
-----
http://www.pythondocs.info
I wonder about what is going wrong here. On the one hand we have
http://www.awaretek.com/tutorials.html with its "more than 300
tutorials", and on the other we have maybe too many people disgruntled
with the main Python documentation.

It seems people want to make better Python documentation and are
willing to put in the effort.
Maybe there is something broken in the process for contributing to the
official documentation?

Personally, I thought it was OK back in 199.... but I did program in
several other languages, including scripting languages, before Python.

- Paddy.

Sep 17 '06 #19

P: n/a
On Sunday 17 September 2006 04:31, Brad Allen wrote:
Here is an idea for improving Python official documentation:

Provide a tab-based interface for each entry, with the overview/summary
at the top-level, with a row of tabs underneath:
1. Official documentation, with commentary posted at the bottom
(ala Django documentation)
2. Examples wiki
3. Source code browser with a folding/docstring mode
4. Bugs/To-Do
I like your idea. The MySQL documentation site just came up to my mind.
Users can write comments to articles there. And the documentation team can
pick them up and include them in the official documentation. What annoys
me most about the Python documentation is that it may be technically
complete but a human being will never figure out how to solve the puzzle
of 50 class methods without getting a proper example. It's like showing
some non computer scientists a syntax diagram to get them started with
something.

For today I plan to check out the SVN repository containing the official
Python documentation and see how well I can contribute. But since many
people are probably good Python programmers but less good in maintaining
complex documentation structures (especially in LaTeX) it might help to
allow more direct contributions. Ubuntu's Launchpad for example contains a
component where anyone can help translate docstrings for Debian/Ubuntu
packages. No more knowledge needed.

At least it doesn't appeal to me if Python's documentation team says "just
open up a bug report on sourceforge - we will deal with the rest". Perhaps
this is a decent approach considering the quality of contributions. I
can't tell.

Christoph
Sep 17 '06 #20

P: n/a

Rakotomandimby (R12y) wrote:
On Sat, 16 Sep 2006 12:30:56 -0700, Robert Hicks wrote:
That said...the Python docs are open source. Just start going through
them and adding examples.

ASPN (activestate) is a good place for examples...
Yes, but that requires a separate search and depends on an external
organization. Wouldn't it be great if relevant examples were a single
click away from official documentation on any given module? Examples
could either come in via a wiki approach, or maybe in some cases from
the doctests, which would be nice to have alongside handy access to the
source code.

Sep 17 '06 #21

P: n/a
That said...the Python docs are open source. Just start going through
them and adding examples.
ASPN (activestate) is a good place for examples...

Yes, but that requires a separate search and depends on an external
organization. Wouldn't it be great if relevant examples were a single
click away from official documentation on any given module? Examples
could either come in via a wiki approach, or maybe in some cases from
the doctests, which would be nice to have alongside handy access to the
source code.
Since the activestate site is already an established repository for
code snippets and examples I don't think it would be a good idea to
start a new one. What would be very useful though is more visible
links on the python.org site to the activestate repository where
appropriate. I'm not sure the pyhon.org people would want to promote
activestate though, nevertheless it would be a great help to many.
Sep 17 '06 #22

P: n/a
Somehow all of the above discussions did not mention having examples or
demos "built-in" for the language itself:

majorfunction.example()
demo("package") or package.demo()
search engine in local html documentation
apropos()

The statistical software R is bettter in this respect if you really
wanted such kind of help.

-Ernie Adorio

Sep 17 '06 #23

P: n/a

ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.
There is *already* an online collaborative project for the Python
tutorial and reference :

http://pytut.infogami.com/
http://pyfaq.infogami.com/
http://pyref.infogami.com/

Please contribute to these.

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml
Regards,

Nicolas.
-----
http://www.pythondocs.info
Sep 17 '06 #24

P: n/a
ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.

Regards,

Nicolas.
-----
http://www.pythondocs.info
Personally, I never found the Python docs particular bad. It is
rewarding to write good documentation because documentation has
different aspects i.e. introductory/tutorial, exhaustive/manual and
design documentation aspects. Not to mention cookbook recipes.

I also observe that the discussion about Python docs is very tool
centered and my question to all the people who believe to improve the
Python docs by converting old tuturials into Wikis is that: what are
the precise requirements? Will an internet connection soon be necessary
to know how the sys module works? Are there any thoughts about
integrating 3rd party module/package documentation with the docs of the
stdlib / tutorial / language ref etc.so that they finally find their
logical place in the system ? Are there any intentions to create an
informational PEP regarding documentation in any forseeable future or
shall documentation projects continue to start in the wild?

So far I've not seen a documentation project ( besides the "official"
one of course ) that provided qualified criticism and didn't suffer
from a second system syndrome.

Sep 17 '06 #25

P: n/a

Kay Schluehr wrote:
Personally, I never found the Python docs particular bad. It is
rewarding to write good documentation because documentation has
different aspects i.e. introductory/tutorial, exhaustive/manual and
design documentation aspects. Not to mention cookbook recipes.

I also observe that the discussion about Python docs is very tool
centered and my question to all the people who believe to improve the
Python docs by converting old tuturials into Wikis is that: what are
the precise requirements? Will an internet connection soon be necessary
to know how the sys module works?
+1 that downloadability is an important requirement; wiki does not
preclude this
-1 on wiki as the only approach; wiki could be an adjunct to officially
managed docs
Are there any thoughts about
integrating 3rd party module/package documentation with the docs of the
stdlib / tutorial / language ref etc.so that they finally find their
logical place in the system ?
This could become a natural progression once a full-featured
documentation system is in place.
Are there any intentions to create an
informational PEP regarding documentation in any forseeable future or
shall documentation projects continue to start in the wild?
Sounds like a great idea. We should probably do more brainstorming and
discussion about the particulars before someone spends a lot of time
writing a PEP. We could create a separate topic in this forum, titled
something like 'Ideas for a new PEP on Python.org documentation
structure, UI, and processes'.

Sep 17 '06 #26

P: n/a
On Sun, 17 Sep 2006 18:10:51 +0200,
Daniel Nogradi <no*****@gmail.comwrote:
start a new one. What would be very useful though is more visible
links on the python.org site to the activestate repository where
appropriate. I'm not sure the pyhon.org people would want to promote
activestate though, nevertheless it would be a great help to many.
There's no reason not to link to ActiveState... but are there RSS
feeds or some similar mechanism to get all the recipes for a
particular module?

Fredrik Lundh also proposed a way to publish examples that get linked
from the documentation <http://effbot.org/zone/idea-seealso.htm>, and
there's some code in the Python sandbox for incorporating links
(sandbox/seealso).

However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.

--amk
Sep 17 '06 #27

P: n/a

A.M. Kuchling wrote:
However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.
That sounds like another good reason to handle the examples at
python.org, but it argues against a wiki approach for examples. Maybe
the examples should be part of the same SVN repository; if they are
implemented as doctests they can be validated before each new release.
On the other hand, that probably only works for very simple examples;
I've seen some extensive examples at in the Cookbook that might not fit
well into a doctest.

There could a separate tab for "Links" alongside tabs for
documentation, svn source, doctests, discussion, bugs/requests, wiki.
The links tab might have a disclaimer to the effect of "Your Mileage
May Vary", and each link might have a date posted next to it. The
links might not all be examples; they could point to alternative tools,
related resources, more discussion -- whatever the community comes up
with. Eventually, someone would have to prune; the dates would help
with that. Also, if folks could rate the links, the best ones might
float to the top.

Sep 17 '06 #28

P: n/a
On 9/17/06, A.M. Kuchling <am*@amk.cawrote:
On Sun, 17 Sep 2006 18:10:51 +0200,
Daniel Nogradi <no*****@gmail.comwrote:
start a new one. What would be very useful though is more visible
links on the python.org site to the activestate repository where
appropriate. I'm not sure the pyhon.org people would want to promote
activestate though, nevertheless it would be a great help to many.

There's no reason not to link to ActiveState... but are there RSS
feeds or some similar mechanism to get all the recipes for a
particular module?

Fredrik Lundh also proposed a way to publish examples that get linked
from the documentation <http://effbot.org/zone/idea-seealso.htm>, and
there's some code in the Python sandbox for incorporating links
(sandbox/seealso).

However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.

--amk
I think that, clearly, a combination of community and automation to
gather the best information from around the tubes is a good thing to
be explored further. However, without careful editing and eventual
integration into the official documentation, the information will just
stagnate under the rug.

Beyond just getting more information into the documentation, which
already covers everything if you know where to look, we need to
seriously take a look at how newcomers are thinking about the problems
they have and where they expect to find the answers. Perhaps some
rearranging of the documentation is in order, or some cross-references
to be added. These aspiring pythoners are asking "How do I do X?" and
there is no clear path to many of their answers without knowing the
answer yourself. That is the problem, more than any lack of examples
or clarity in the text.

How can we solve this? We need a two fold approach to improving the
documentation. We need to increase community support of the official
documentation, perhaps with forums/wikis attached to different parts
of the documentation for the dropping of examples, links, and
suggestions, along with discussion on how to further improve them. Add
a form (built into the wiki?) right there with the docs where people
can submit additions, corrections, expansions, and other changes to
request.
Sep 18 '06 #29

P: n/a

Brad Allen wrote:
A.M. Kuchling wrote:
However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.

That sounds like another good reason to handle the examples at
python.org, but it argues against a wiki approach for examples. Maybe
the examples should be part of the same SVN repository; if they are
implemented as doctests they can be validated before each new release.
On the other hand, that probably only works for very simple examples;
I've seen some extensive examples at in the Cookbook that might not fit
well into a doctest.
doctest is not the only way to present examples in code. The other one
is simply a link to the lib/test directory and the approriate
test_<module_name>.py module. Reading testcases is often the only
source I have when I want to understand how something works ( exercise:
try to create a code object from scratch using the new module and the
desciption provided in the docs ). I find Cookbook recipes a little
over the top for basic use pattern. They are usually not that well
factored that they present a single idea precisely.

Since we are at it: what about two additional directories within the
Python system namely "site-docs" and "site-test" for all kinds of
docs/tests of 3rd party modules/packages? Installing docs using
distutils might automatically update a single HTML site that contains
references to the package docs ( de-installing will cause another
update ).

Python24+-docs
+-site-docs
+-lib
+- test
+- site-test

or alternatively:

Python24+-lib
+-site-packages
+- site-docs
+- site-test

Executing all testcases of the stdlib already uses reflection over the
modules provided in the directory. Same basic mechanism could be
applied to site-test.

Note that once such an architecture is fixed there is no reason (
besides bandwidth of course ) not to use svn to manage user projects
within site-space completely. I would go even further and suggest to
implement some svn management functions within the Python console such
as:
>>svn.show_projects()
proj = svn.open_project(project_name)
proj.checkin(module_name)
proj.checkin_all()
svn.checkout(another_project)
etc.

Sep 18 '06 #30

P: n/a
ni*******@gmail.com wrote:
>
That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info
Frankly I'm tired of these yet-another-wiki announcements!
Who is supposed to fill them with content?

If you have improvements to the official docs put them into Python's SF
tracker:
http://sourceforge.net/tracker/?func...70&atid=305470

Ciao, Michael.
Sep 18 '06 #31

P: n/a
ni*******@gmail.com wrote:
Wildemar Wildenburger wrote:
>ni*******@gmail.com wrote:
>>I have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
Where have you read that?

wildemar

I don't mean to start a flame war about this but here are some
reference of people, who like me, don't like the current python doc:
http://xahlee.org/UnixResource_dir/writ/python_doc.html
Xah Lee is a well-known crank.

--
bruno desthuilliers
python -c "print '@'.join(['.'.join([w[::-1] for w in p.split('.')]) for
p in 'o****@xiludom.gro'.split('@')])"
Sep 18 '06 #32

P: n/a
Rakotomandimby (R12y) wrote:
On Sat, 16 Sep 2006 22:43:41 +0200, Daniel Nogradi wrote:
>Then how about running your site on python and not php?

PHP has "better" documentation... ;-)
More seriously, I can provide a CPS hosting to nicolasfr if he wants.
Alert ! Unusable undocumented monstruosity ahead...

--
bruno desthuilliers
python -c "print '@'.join(['.'.join([w[::-1] for w in p.split('.')]) for
p in 'o****@xiludom.gro'.split('@')])"
Sep 18 '06 #33

P: n/a
ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.
I agree in some ways, Python docs could have better organization (more links
between related things).
That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.

Regards,

Nicolas.
-----
http://www.pythondocs.info
Here is another URL of such a project, i bookmarked some times:
http://www.simisen.com/jmg/cpd/
And there is nothing beyond this URL, like many of such projects.

AFAIR there is a starting of Wiki documentation - like PHP docs, one page
per function, contributors comments & Co, from one main Python developers
(dont remember who start this neither what is the URL).

In all case, dont setup another new system, use
http://wiki.python.org/moin/, at least your work will not be lost.

A+

Laurent.

Sep 18 '06 #34

P: n/a
ni*******@gmail.com wrote:
Hi,

I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated sentences that you
need to read 10 times before understanding what it means.

That's why I have started a collaborative project to make a user
contributed Python documentation. The wiki is online here:
http://www.pythondocs.info

This is a fresh new website, so there's not much on it, but I hope to
make it grow quickly. Help and contributions are welcome; Please
register and start posting your own documentation on it.

Regards,

Nicolas.
-----
http://www.pythondocs.info
You're realy nor the first one, see
http://mail.python.org/pipermail/pyt...ay/219580.html
(and following thread)

Other (never achieved) projects... http://www.pythondocs.org/

Even Skip Montanaro python-glossary site seem to not have been continued...
http://mail.python.org/pipermail/pyt...ay/219682.html
Sep 18 '06 #35

This discussion thread is closed

Replies have been disabled for this discussion.