[pygame] Improving pygame web docs

[Greg Ewing <greg.ewing@xxxxxxxxxxxxxxxx>]

jug wrote:

> http://pygameweb.no-ip.org/docs/surface.html ist not really easy to 
> read, but I don't know exactly why.

It looks all right to me, except for one thing: Every
link to the docs for a method embedded in the text
seems to be followed by a comment in small print, e.g.
in the paragraph about Surface.convert,

  ...arguments can be used, similar to the
  pygame.Surface - [pygame object for representing
  images] call...

IMO these embedded comments are pointless and
distracting and make the text hard to read. Just
make the method name into a link and leave it at
that.

Also a minor suggestion would be to leave some
space between the heading for a method and its
call prototypes, and between the prototypes and the
following text, e.g. instead of

  Surface.convert - change the pixel format of an image
    Surface.convert(Surface): return Surface
    Surface.convert(depth, flags=0): return Surface
    Surface.convert(masks, flags=0): return Surface
    Surface.convert(): return Surface
    Creates a new copy of the Surface with the pixel format
    changed. The new pixel format can...

space it out slightly:

  Surface.convert - change the pixel format of an image

    Surface.convert(Surface): return Surface
    Surface.convert(depth, flags=0): return Surface
    Surface.convert(masks, flags=0): return Surface
    Surface.convert(): return Surface

    Creates a new copy of the Surface with the pixel format
    changed. The new pixel format can...

Also generally leave space between paragraphs if you're
not going to indent the first line of each paragraph.
Otherwise the text tends to look like one huge paragraph,
which is not good for reading.

--
Greg