Hi Stan,
I've had a look over the progress so far, and have lots of feedback :)
(surprise!!!)
Firstly, I'll point back toward 2 things Frank said to me back when
he reviewed the initial (C APIs) version of this doc: there is alot
of value to be had by walking through a real example program; and
its not worth duplicating info in the man pages. Although, in an
ironic twist neither of us foresaw, there may be some value in that
now we come to do python docs (wrt python API reference, which wont
be in the man pages).
I've written a simple, yet still realistic & useful (I hope) example
program - a python implementation of uptime(1). Attached; for your
review/perusal/amusement ... somewhere in section 3.9 - "Programming
Issues and Examples" would suit if you like it, after the C example
perhaps. Sadly, it does not yet work - its exposing a bug in the py
wrapper code for pmLocaltime(3) - also affects pmCtime(3) I think.
We'll need to crack these, I think both are using double indirection
where they need to use single, or are not allocating the buffer right,
or something along those lines. A new QA test will be needed too -
I'll keep going on fixing these problems early next week (unless the
problem is clear to you - feel free to fix it before then). :)
In terms of the docbook-fu so far - what you've got is looking like a
dup of the C section, with much less content, and backward references
to the C API docs. This is making use of the handy fact that the way
the python wrapper was done, a programmer basically needs to know the
way the C equivalents work (ctypes, etc). As such, it seems like we
could take a simpler approach - instead of duplicating the entire 3.8
section (PMAPI Procedural Interface), and making separate C / Python
versions - which is alot of docs! - I'd recommend instead documenting
both together. So, where each C interface has an initial <literal-
layout> tag then the C API, add just below that (still inside that
<literallayout> tag) the python version. Then no back referencing is
needed, and no docbook index updates, and so on - which complicating
your changes atm. Any Python specific notes can go right in there
alongside the C notes.
This makes alot of sense I think, since a Python programmer will need
to grok the C API anyway in order to understand all the ctypes stuff.
All the subtleties of each API call are documented in the C docs, so
it'd be alot easier to read for a python programmer learning the API
for the first time, I think.
> pmParseInterval Function
> (struct timeval, "error message") = pmParseInterval("time string")
> parse a "time string" into a timeval struct. For more information see
> the C function description.
[ kept that there as a simple example of the points above, randomly
chosen - just showing the level of verbosity -> not much value-add
for the py docs IMO - so I think merging 'em in with the C APIs is
going to work out OK. ]
So, beyond having an example, and merging the python/C writeups, I'd
like to see somewhere a paragraph or three about the python-specific
issues - things like: what to import, the classes & modules, how the
context class works (constructor -> pmNewContext, & destructor does
pmDestroyContext, magically) - these could live in a new section in
3.7 "PMAPI Programming Style and Interaction". Already in there is
a sub-section on error handling - we should discuss using exception
handling there for python calls. And right in amongst the existing
docs is best I think - e.g. its useful for a python programmer to
know about "pmerr -l" as well. There's a later section going more
into "Handling PMAPI Errors" (3.9.5) - an example in there would be
great. It would be worth reading through Chapter 3 in its entirety
and marking C-specific things as just that, adding in new python
words throughout, and leaving all the generic/common stuff as is.
Then, if you're still standing :) - retreat to Chapter 2 and repeat
the exercise for the PMDA interface - we already have pmdasimple in
python, so it should be easier (thats the example used there, IIRC).
And if you get that all done (by end of tomorrow? hahaha), the PMI
(import) API is missing entirely, both C and python variants... ;)
cheers.
ps: $ pylint uptime.py
Your code has been rated at 10.00/10
/me does his happy dance ... if only the code actually worked!!!
--
Nathan
uptime.py
Description: Text Data
|