[Python-Dev] The docs, reloaded

Ron Adam rrr at ronadam.com
Sat May 26 22:59:04 CEST 2007


Georg Brandl wrote:
> Hi,
> 
> We managed to get an up to date version of the web version of the docs running
> on the server. The address is still the same (http://pydoc.gbrandl.de:3000) and
> it's also still running on top of wsgiref.
> 
> Changes so far:
>    * comments: each page that is generated from an rst file can have some
>      comments attached to it. Commenting doesn't require registration at the
>      moment.
>    * antispam with optional reverse captcha (captcha for bots, a hidden input
>      field named "homepage" which bots hopefully fill out, dumb as they are) and
>      a regular expression filter rules based on MoinMoin's BadContent file.
>    * administration panel for moderating comments. You can find the admin panel
>      at http://pydoc.gbrandl.de:3000/admin/ -- login credentials are
>      testuser:password)
>    * feeds for comments on a page or the last n comments on the whole site.
>    * source view is text only (again).
> 
> What still works:
>    * intelligent error pages: if a page does not exist the URL path is used to
>      conduct a fuzzy keyword search (see below).
>    * fuzzy keyword search: "os.path.exists" jumps to the entry, "os.paht.exists"
>      shows some possibilities.
> 
> What needs to be implemented:
>    * full text search
>    * proposing documentation patches
> 
> Note that the comment area is really, really dark, that's intentional.  This is
> meant to visually separate comments from the official docs, but if the constrast
> is deemed to unsettling, another way can be found.
> 
> Also, we're experimenting with alternate stylesheets, e.g. placing the sidebar
> on the right of the main text, or a "traditional" style for those liking the
> original docs' style.
> 
> In any case, we're waiting for your input!
> 
> cheers,
> Georg and Armin

Yes, the comments are a bit too dark.  The separation could be done better 
by moving it below the footer.  Or better yet, duplicate the navigation bar 
between the the document page and the comments.


   ------------------------------------------------
   crumbs                                navagation
   ------------------------------------------------
     side |    main page
     bar  |
          |
          |
   ------------------------------------------------
   crumbs                                navagation
   ------------------------------------------------
       User Comment section


   ------------------------------------------------
                    copy right
   ------------------------------------------------


The user comment section could have it's own side bar if that's desirable.

Also the python version information needs to be on every page someplace.


Ron


More information about the Python-Dev mailing list