[docs] how about adding anchor tags to the functions

Sandro Tosi sandro.tosi at gmail.com
Sat Nov 19 19:27:18 CET 2011


Hello James,
thanks for your feedback.

On Sun, Nov 13, 2011 at 19:20, James Lin <guanfenglin at gmail.com> wrote:
> Hi there,
>
> First of all, hands down to the effort for the detailed Python
> documentation.
>
> I was a long time PHP programmer and enjoyed the PHP documentation style,
> single page of specific function documentation and samples, then community
> contribution.

this is just my opinion, but the the times I needed to look up how to
use a php function, I tended to find those comments quite confusing,
and actually hiding the real information I was looking for.

Community contributions are important and for sure valuable (that's
what we're here for after all :)) , but I think some kind of
"filtering" to provide high quality documentation is important too.

> While I agree Python is different to PHP, but I think the
> Python ducmentation still has room to improve and the community should still
> be able to "borrow" some goodies from the PHP documentation style.
>
> Perhaps I may not be the first one who suggested this, but I do find having
> the anchor tags on the function names(so google can index and provide
> directly to the specific section) in the doucmentation really reduce some
> frustration on reading the python documentation.
>
> eg. if I am searching "python urllib urlretrieve" and google results page
> shows the relevant information but with this link here
> http://docs.python.org/library/urllib.html, then I am required to do another
> page search to locate the information i want, it would be great that if the
> site provides links like
> http://docs.python.org/library/urllib.html#urllib.urlretrieve

I don't think I understand: this link is actually provided, or are you
asking to split every function/class/method in a separate page?

>, so the
> browser automatically scrolls to the right section? Also, it would be
> awesome to have some code examples of each function, if that's too much

The python documentation provides some examples, but most often the
function usage is straightforward, and doesn't require any additional
examples, that's at least my experience.

> effort needed, how about having a collapsed community section(similar to
> PHP) under each function?

That's more difficult than what may seem: the documentation provided
at docs.python.org is generated from files maintained along the python
source code. They are reviewed and expanded also from users
suggestions, but I don't think allowing free-editing from anyone would
actual provide a better doc that the one we have.

Thanks for your interest in making Python doc better,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi


More information about the docs mailing list