Review, then use new docs on website.

Issue #149 resolved
René Dudfield created an issue

The new docs are generated with sphinx and other docs tools from the hg head of pygame version control on the website server.

However, the docs need review before replacing the old docs.

Please review the docs here:

Comments (18)

  1. Radomir Dopieralski

    Clicking on the "Search for examples of <function name>" button takes to a google page that says:


    Sadly, this service has been shut down. (please see the official blog post and the discussion for details.)

    Much of Code Search's functionality is available at Google Code Hosting including search for Chromium.

    We're very sorry for the inconvenience.

    -- Your Google Code Search team

  2. René Dudfield reporter

    The code search has been fixed :)


    • I noticed the css on the reference index page could use some improvement:
    • finish converting .html files into restructured text ( @thesheep has been doing this nicely so far :)
    • decide on how comments would work... disqus, vs website comments, also keeping the comments up to date when distributed (should we distribute comments at all?).
    • if wiki is going to be in reStructuredText too, decide if it is a good idea to include it into the published documentation?
  3. Thomas Kluyver

    What's the process to upload the docs? Those files should be generated or copied into place by Sphinx.

  4. René Dudfield reporter

    There is a cron job that runs every 5 minutes or so...

    cd ~pygame/pygame
    hg pull && hg update
    make docs
    rsync -va --delete docs/ ~pygame/www/docstest/
  5. René Dudfield reporter

    There was an issue with 'make docs' in that it thought everything was already built. 'make docs' is still broken, but I made the script call 'python' instead, and the url has the css etc now :)

  6. Thomas Kluyver

    Ah, maybe a Makefile task with a dependency on a whole folder doesn't check the contents of the folder? Anyway, glad to see that's resolved.

    I don't think there's a pressing need to distribute either comments or the wiki content - I suggest we keep it simple and just distribute static docs, while the comments and the wiki live on the website. I don't have any strong feelings about how the comments are handled online.

  7. René Dudfield reporter

    How are the docs looking now? Any remaining issues before we replace the existing ones?

    Only thing left to do is the comments I think. We either replace the comments we have with disqus based commenting, or use the existing add comment functionality (with all the spam problems it has).

    Using disquss would require a JavaScript to load the comments when people click, rather on page load, since it a bit harder. Also disquss isn't really designed to have multiple sets of comments on one page. It's designed around one set of comments per page.

    If we use the existing php commenting system, we need to copy the various .php files in when we rebuild the pages and publish. Not too hard.

    The easiest way is for now to just use existing php commenting, and fix the publish step. Then we can deal with a new or improved commenting system as a separate task.

    I agree distributing the comments or wiki content is not a big need at the moment.

  8. dreamer9atlassian

    I took a more detailed look at the new page, comparing the old ones side by side, so far camera --> image

    Nothing major found, but a few things:

    • typo on the Event page which is also on the old site: "Pygame handles all it's event messaging through an event queue" ... should be "its" no apostrophe. Although in the spirit of maintaining the feel of the old site ... maybe it's a feature not a bug? haha.

    • the new yellow box for example code needs to truncate at the termination of the code. Right now it stretches across the page and that looks klunky imo. I'm using OSX Lion / Chrome .

    • instead of the 'method -> returnvalue' syntax, can we go back to 'method : returns returnvalue' ? I think that's clearer and more pythonic.

    • on the new site, many method calls use the standard font whereas on the old they're monospaced. I think the old site is more readable in this way. Lots on the event page here. I could compile a comprehensive list if that's helpful?

    • can we go back to a serif font for description? I think it has more personality than the non-serif we're using for most of the new pages, and is definitely a personality site haha.

  9. René Dudfield reporter

    Thanks for your feedback :)

    1. I fixed a couple of the "it's" usages.
    2. I made the pre code blocks inline-block, to only take up width of the code, not 100% width.
    3. hrmmm... not sure about this. It's a fair bit of work. I'm not sure what is better.
    4. The fonts for method calls all seem monospaced to me... can you point out a specific one? Maybe I'm looking at something else.
    5. The current website uses sans-serif... so using that for the moment.

    Thanks again.

  10. dreamer9atlassian

    I finished looking at the rest of the docs, joystick -> version, and here are a few small details

    1. Math - there is a typo with "Modul" and what looks like a hanging \w tag
    2. mouse - examples to get mouse events needs cleanup where the 'or' is separating two blocks of code.

    If this is updated from hg commits then maybe I can take a look at a fix myself and submit a patch? It would be a good learning experience.

    Also -- regarding the Serif font - on the old site, there was a combination of monospaced and serif font, and imo it make the docs more readable especially for a bit page like the sprite module.

  11. Log in to comment