[Developers] Plone cleanup

[Arni Magnusson]

Sorry, I didn't know about the proxies.

I think the API Documentation is quite functional as it is now. People 
looking for ADMB references will click 'Documentation' - 'Manuals' and 
find a link to the current Doxygen Tree that they can browse.

People that would like to contribute additional API documentation will 
click 'Documentation' - 'Developers' - 'API Documentation' and find 
detailed instructions on how to go about. In the same place they will find 
a link to the current Doxygen tree.

So the documentation itself is not restricted to the 'Developers' section, 
only the detailed guidelines on how to write additional documentation. 
Hosting the Doxygen tree outside of Plone is a practical thing to do, and 
faking it with a proxy doesn't serve any obvious purpose. The Foundation 
website can host the newsletter and the Doxygen tree, and both are 
prominently linked from the Plone pages.

At the La Jolla meeting, we encouraged core developers with SVN write 
access to add Doxygen to existing code anytime, and others to send Doxygen 
commented source file updates to Johnoel. Since then, I uploaded 
keywords.txt to identify classes and methods that are likely to be looked 
up by users.

John made an effort to test both the "Doxygen" and "Javadoc" style. I 
agree with him that the default "Doxygen" style works better, and that we 
can safely remove all traces of "Javadoc" from the guidelines and 
elsewhere. It was a worthwhile test, since we didn't know beforehand which 
style would work better with ADMB, or if both were useful.

Arni



On Fri, 18 Jun 2010, John Sibert wrote:

> I'm glad to see that the material was not lost, but something is 
> definitely broken. As I recall, there were some proxies on the plone 
> site that pointed to directories at admb-foundation.org. These proxies 
> were probably lost when the NCEAS folks tried to update the hosting or 
> when you moved the material to a different directory. Johnoel set them 
> up, but I cannot remember what they were. Perhaps Johnoel has some 
> insights. Perhaps proxies are a bad idea for this purpose?
>
> More generally, I'm not sure the API documentation belongs in the 
> developers section. In the long run, users should be able to refer to 
> the on-line API dox. True, the draft API documentation was created in 
> part to generate some feedback, but I have received very few comments 
> about the draft. Assuming that few comments are forthcomming, I'm ready 
> to conclude that the API docs are OK as is, that we prefer the default 
> doxygen style (in lovely ADMB greens), and that we can omit the javadocs 
> style from further consideration.
>
> Cheers,
>
> John
>