There were some remarks regarding the documentation some days ago, and I
would like to add some of my own.
I like your software very much and I write this in the intent of helping
it to be even beter, please take my critics as constructive ones, that's
how I hope they will sound to you.
Often colleagues ask me how I made this or that figure, so I talk about
pyx. There are 3 main remarks I make always to my colleagues:
1. it's a powerfull library putting python, PS and latex together with
utilities for easy plotting;
2. it's hard to go through the documentation;
3. developers change the API with every release (breaking anything you
might have done before).
I have some suggestions regarding the last two:
About nr. 2:
The way I see, the examples page is more of a show room for prospective
users to look at than an actual tutorial.
I would greatly appreciate if there were examples in the docs
themselves. You don't need to include a throughout example but just a
line or two showing how to use the particular class instance being
I'm often re-reading the docs and going back and forth searching for an
example of something in the examples page (and not finding it)...
I mean: At times a picture is worth a thousand words and at times a code
line is also worth many words.
The "graph.style: Styles" page comes to mind when I think about
something that I always have trouble with.
While it's not stricly true that everything break after a new release,
everything I have does break very often.
I know that pyx is still alpha and you reserve yourselfs the right to
change lot's but you must understand the burden that causes to your
brave users ;-)
Problem is: I don't do figures everyday, but every once in a while
(paper, talk, conference etc) and everytime I discover I have to go
through the Docs again because my own examples don't work anymore.
It would help me terribly if you guys also produced a listing of things
that got broken, just a listing would already help; a list and 2 lines:
old API -> NEW API, would do wonders.
Most of the doc text does not change in the upgrades and I find it
difficult (and time consuming) to keep searching for whatever might have
changed that might be screwing up my "new-release" broken code.
Yes, I do save all EPS files... problem is I start new figures from
older small examples that I have lying around. Perhaps if there was code
examples in the docs that wouldn't be so much of a hassle.
(I've tryed the changelog for that does not help much).
Sorry, for the long email, have to flee now, back on monday after