[orm-devel] documentation:

[Werner F. Bruhin]

Hi Diedrich,

Great that you are going to update the Firebird adapter.  I haven't had 
any time lately to look and/or work on ORM, should have at time to help 
at least on the testing side of things in a couple of weeks time, so let 
me know whenever testing will make sense.

See you
Werner

 Diedrich Vorberg wrote:

>Hi Charles,
>
>  
>
>>I started looking into the various utilities available to assist python
>>documenation.  Docutils definitely looks like a good choice for general
>>documentation.  I also came accross epydoc (http://epydoc.sourceforge.net)
>>which yields instant gratification in the form of API docs.  I'll send an
>>attachment of the output generated (using latest CVS src) in a subsequent
>>message to avoid binaries on the list.
>>    
>>
>
>this sure looks nice, kind of like JavaDoc output. Their docstring
>format is even close to (re) Structured Text. I think good API
>documentation is a must-have, but maybe even more important is good
>conceptual documentation. An FAQ would be nice and the introductory
>text orm.docbook needs an overhaul.
>
>As a first step I've taken an hour or so and added a number of
>docstrings for classes and methods I've added or modified during the
>past weeks. There is still much work to do here, but I think the
>comments in orm's are quite usefull compared to other projects.
>
>If you, Charles, have a couple of hours to spare I'd ask if you'd like
>to go over the comments, check them for comprehensibility, correct my
>poor spelling and while doing this start converting them to pydoc's
>format. This might even be a good way for you to learn about orm, so
>you'd be rewarded with personal benefit for your contribution ;-)
>
>Today I plan to look at the firebird adapter. I'll port the example
>programs to it and see how it works.
>
>Step three will be an overhaul of the non-docstring prose
>documentation. I plan to convert it to reStructuredText with some
>additions (syntax highlighting, CSS, etc). Also I'll add information
>on the things in orm that have changed since this document has been
>written. I'll probably put together an FAQ or a "cookbook", though I
>think adding extensive comments to the example application might do
>the job just as well as that even or better. People dealing with this
>*are* programmers and the examples seem like a very efficient way of
>conveying how orm works.
>
>Finally I'll start documenting the user interface stuff. I think it is
>very powerfull, but I don't think you can make head and foot of it
>without good documentation. Also this modules are far from being
>completed. I expect this to happen after the 1.0 release.
>
>This toppic being raised, I've decided to call the next stable orm
>release 1.0, bacause after that I'll change the infrastructure to use
>metaclasses. Also a lot of identifyers are going to change, too
>(practically all used by orm in dblcasses. I'll switch to Python's
>naming convention and use variable method names that look
>__like_this__ .) Wrapper classes for the old format will be provided
>and your current datamodels need not to be modified. Anyway, before
>1.0 I'd like to make firebird work again and revamp the
>documentation. 
>
>Diedrich
>
>  
>