Documentation for python-evolution - where?

[tinnews]

I'm trying to use the python evolution (as in Gnome Evolution) module
but I can't find any documetation beyond the odd trivial example and
the API documentation at http://doc.conduit-project.org/evolution-python/
(or similar places presumably).

The trouble with the API documentation is that it tells me that
evolution.ebook has three functions:-

get_self_contact(...)
list_addressbooks(...)
open_addressbook(...)

but then there is no documentation at all that I can find which tells
me what the functions return and the functions/methods that can be
called on the returned data.

I know that open_addressbook() returns an address book (surprise!) but
then, except for what I can glean from the examples I can find, there
doesn't seem to any documentation on what methods I can call on the
returned address book to extract data from it.

Can anyone point me at anything with a bit of detail about the
evolution module?

 

[Chris Angelico]

I'm trying to use the python evolution (as in Gnome Evolution) module
but I can't find any documetation beyond the odd trivial example and
the API documentation at http://doc.conduit-project.org/evolution-python/
(or similar places presumably).

One of the downsides of software you don't pay money for is that, all
too often, there's little or no documentation. One of the upsides of
free software is that you can look at the source code. I don't know
anything about Python-Evolution, but if you're prepared to do a bit of
digging, you can probably find what you want here:

http://git.gnome.org/browse/gnome-python-desktop/tree/evolution/

(You probably have a copy of the same content on your own hard disk
somewhere, too.)

Once you figure out what you wanted, do consider sending a patch to
the maintainer(s), improving the docstrings and/or external
documentation, so the next person has an easier task.

Chris Angelico

 

[tinnews]

One of the downsides of software you don't pay money for is that, all
too often, there's little or no documentation. One of the upsides of
free software is that you can look at the source code. I don't know
anything about Python-Evolution, but if you're prepared to do a bit of
digging, you can probably find what you want here:

http://git.gnome.org/browse/gnome-python-desktop/tree/evolution/

Yes, thank you, I couldn't even find that.

(You probably have a copy of the same content on your own hard disk
somewhere, too.)

Once you figure out what you wanted, do consider sending a patch to
the maintainer(s), improving the docstrings and/or external
documentation, so the next person has an easier task.

Actually I'm not sure if it's down to the docstrings because the help
available from Python itself stops (not unreasonably) at the interface
to the C library code. What I was after (and you have told me where
it is) was the functions/methods available from the C library.

 

[Chris Angelico]

Actually I'm not sure if it's down to the docstrings because the help
available from Python itself stops (not unreasonably) at the interface
to the C library code.  What I was after (and you have told me where
it is) was the functions/methods available from the C library.

Ah, yes, I know that problem! Let's see, how many high level
languages/libraries have I used that have simply exposed a lower-level
API without documenting it? REXX/REXXUtil and SysSetObjectData was the
first. More recently, Pike and the GTK/GTK2 modules. In between, oh so
many others.

Depending on how much is exposed and how transparent the local layer,
it may still be worth writing up some better documentation. Or if not,
it may be of value for the docs to incorporate a link to some
"upstream documentation", which would accomplish the same thing. (It's
a shot at immortality - get your name in a big project's revision
history!)

ChrisA