[Pyogclib-developers] Re: The web site

[Sean G. <sgi...@fr...>]

On Tuesday, September 23, 2003, at 11:31  AM,=20
Jea...@cc... wrote:

> Sean,
>
> Sorry for the late reply, I was out of thown this week-end and monday.
>
> First of all the epydoc thing looks great, and you make a good point=20=

> as far
> as docstrings and so on ... I'll be sure to use it as a reference to=20=

> help me
> properly document my code.
>
> Is there a way to have the web site part automatically update itself=20=

> nightly
> something ? Actually, I'm pretty sure there's a way to trigger things=20=

> based
> on CVS activity also, I was reading that somewhere in the SF docs ...=20=

> Maybe
> that could be used ? Though we should probably have such a web site=20
> included
> with file releases, or have verions available on the site based on=20
> specific
> file release versions ? (i.e. view the API for version 0.1, 0.2 and=20
> CVS) ...
> What do you think ?
>
> As for the website, I'm thinking it's good to have, but right now it=20=

> might a
> lot to manage ... What you've done so far looks good, but we should=20
> simply
> point to SF pages where possible (For example, why manage news items=20=

> on the
> website when they can be easily managed in the SF site itself).  OK so=20=

> news
> probably are available through RSS , so that's a bad example, but you=20=

> get my
> point :)
>
> Suggestions:
>
> - I would remove the "project page" link, and a variety of links=20
> straight
> into the various sections of the project page. But I guess that's=20
> personal
> taste ? I'm going on the assumption that the website will become the=20=

> main
> point of entry, and that therefore getting to things from there should=20=

> be as
> direct as possible ?
>
> In keeping with that idea I would:
>
> - Add a link to the CVS information page from the left bar
> - Make the news section a "page" with a link from the left bar, see if=20=

> we
> can access our SF.net news via RSS and use that, instead of=20
> duplicating the
> work. I can look at the RSS issue if you want.
> - The API page might be further divided by version or something, as =
I'd
> mentionned above ?
> - Do the same for as many as it might be deemed useful and comonly=20
> used by
> users/developers (i.e bugs, forums, mailinglists, docs)
> - I would suggest renaming or reformatting "API Documentation" since
> "Documentation" appears on a different line ... I would suggest a
> "Documentation" link that points ot actual docs (README's , HOW-TO's=20=

> etc
> ....), and a link that point so epydocs, maybe "API Browser" or=20
> something
> like that ?
>
> My .02$ ... let me know what you think !
>
> Cheers,
>
> Jean-Fran=E7ois Doyon
> Internet Service Development and Systems Support
> GeoAccess Division
> Canadian Center for Remote Sensing
> Natural Resources Canada
> http://atlas.gc.ca
> Phone: (613) 992-4902
> Fax: (613) 947-2410
>

J.F.,

I am cc'ing this to the pyogclib-developers list since it seems that you
are still stuck in mailman limbo.

All your points are right on.  I don't want to spend any more time than
necessary on the site and would like to use RSS and the sourceforge
project news as much as we can.

Docstrings ... while you are at it, will you put the readme in as a
docstring in ogclib.__init__.py so we can have a package-level
description appear in the epydoc docs?

You're OK with the basic layout and content?

Sean

Aside: I ran epydoc against the Python Mapscript module and it is not
as useful as I'd hope.  None of the method arguments are named, which
I should have expected.