On 31/01/2011 17:56, Paul McNett wrote: > On 1/31/11 8:25 AM, Werner F. Bruhin wrote: >> I thought it might be good for everyone to see what is there today and >> to provide comments on all this, I therefore uploaded what I have >> currently to one of my own sites so people can look at it and comment. > Looks very nice! Thanks, that is 99% Andreas fault;-) , I just took over his layout (.css, .html templates etc) and adapted the .rst generation script to Dabo. >> following needs still to be done: >> - home page clean up, was thinking of basically using the content from >> http://dabodev.com/ and it would be nice to have some nice Dabo >> Application screen shots to replace the "AUI" place holder. > Are we replacing the dabodev.com website, or just the api documentation bits? > If the > latter, we shouldn't IMO duplicate the dabodev.com home page. No I don't want nor suggest to replace dabodev.com. I still think the API documentation needs an introduction page (I'll change "home" to "introduction" and reorganize it a bit.
BTW, I plan to generate not just a web/html version but was also thinking of doing a PDF and possibly also a Windows help CHM one. >> - remove Inheritance diagrams where they don't make sense > I think the inheritance diagrams are very nice. Agree, but currently there is one shown on pages like e.g. dEvents.dEvent, which inherits from a plain Python "object" which isn't even shown on the diagram. These I am planning to remove. >> - clean up the "Module Summary" stuff for each package, currently I just > > use a toctree with "glob" for the package, might be better to define > > content and order for each of them > > We want to be able to auto-generate the api docs nightly, so all the meta > data needs > to (probably) be part of the dabo source tree. That shouldn't be a problem, currently I have a docSphinx folder next to the Dabo package folder and it contains everything to generate the docs, I am on Windows so some stuff will have to be changed if your stuff sits on a Linux box but I try to keep these things as much as possible together. >> - define what should go onto the "Tree" quick access - it is shown on >> the content pages, e.g. "dApp.dApp.html" >> - links/cross references need to be fixed - see below >> - clean up of documentation strings within the code >> - where appropriate convert some code comments to documentation strings > There are/were some docstrings that told too much of the implementation, and > some > comments that mostly describe the interface and should be rewritten as the > docstring. > Agreed. > > Additionally, I think we must remove all the methods that start with _. At > least the > ones that are property getter/setters. > >> Links/cross references problem: >> for example "dabo.dObject.dObject" doesn't work but "dObject.dObject" >> works, or if I change some stuff then the first one works but not the >> second one. I am reporting/asking on the Sphinx list, but if someone >> has an idea please let me know. I believe it has to do with the >> ":module::" and "currentmodule::" definitions, but I haven't found one >> which works for both. > You'll probably run into similar issues where it wants to document > dabo.ui.uiwx.dTextBox instead of the proper dabo.ui.dTextBox. These are > issues with > our namespace mangling, an early design decision that I sort of regret and > want to > fix at some point. > SVN revisions If you look at Andreas site, e.g. page http://xoomer.virgilio.it/infinity77/AGW_Docs/aui.framemanager_module.html#aui-framemanager you will see a SVN Revision graph. Would you like to see this in the Dabo doc? It is done using "viewvc" which doesn't seem to be available on "http://svn.dabodev.com";, i.e. "http://svn.dabodev.com/viewvc"; gives me a 404 error. John sent me some images, will use them for the introduction page unless anything else is proposed. Werner _______________________________________________ Post Messages to: [email protected] Subscription Maintenance: http://leafe.com/mailman/listinfo/dabo-users Searchable Archives: http://leafe.com/archives/search/dabo-users This message: http://leafe.com/archives/byMID/[email protected]
