[orm-devel] documentation:

[Diedrich Vorberg]

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

-- 
Diedrich Vorberg <diedrich at tux4web.de>      .---.   /             \
http://tux4web.de Tel: 02302 425269        /     \ ((__-^^-,-^^-__))
                                           \.O-O./  `-_---' `---_-'
"Unix is simple, but it takes a genius     /`\_/`\   `--|o` 'o|--'
to understand the simplicity."            //  _  \\     \  `  /
                      - Dennis Ritchie   | \     )|_     ): :(
                                        /`\_`>  <_/ \    :o_o:
     Associate Member of the FSF #1245  \__/'---'\__/     "-"