documentation

[Adam]

Hello,

Documentation is still incomplete, but some of it can already be found
at:

http://pycha.yourwei.com/

I still need to add the embed in GTK example and finish the options.
I'm not sure why the definition list in "options" does not make the
terms bold.

I used:

term
definition

term
definition

I'm not sure how the modules should be documented. Sphinx seems to
have quite a few options. Any suggestions?

Adam

[Adam]

Hello,

The GTK embedding example is almost finished. I'll update the website
in a few days.

A few questions about the options:

1. Are the widths in pixels? For example, the lineWidth default is
1.0, so it seems like it's points or mm.

2. There is a 'tickCount' for both axis. It makes sense for the y-
axis, but does it make sense for the x-tick labels to have a count?
The number of labels always equals the number of bars, no?

3. I previously mentioned maybe changing the input method to make it
more easy. Has there been any discussion of changing how options are
handled? The problem with the current approach is that it's very easy
to make mistakes when writing a huge dictionary (missing commas,
brackets, etc.). It's also very difficult to change just one option
that's nested deep in the dictionary (user changes the color of bars
using a gui, for example).

I think it's easier to use attributes:

You can set many options:
chart.set_yaxis(title = 'X', lineWidth = 1.0, tickCount = 5)

Or just one option:
chart.set_xaxis(title = 'Y')

You could provide a chart.get_ option method also. This is very useful
for embedding PyCha in apps.

Adam

[Lorenzo Gil Sanchez]

Hi Adam,

thanks for this contribution: we really need better documentation in pycha.

Some comments about the current draft:

- I would put the tutorial before the options description, since the
later is more like a reference sheet.
- In the installation section, Linux subsection I would say:

There are three ways to install Pycha in Linux:

Option A:
Use your distribution package system. E.g. for Ubuntu you can write:
apt-get install python-pycha
Benefits: better integration with your distribution. It can be
uninstalled easily. Good for newbies

Option B:
Use easy_install to get the latest official version. You need to
install the setuptools package to use easy_install.
Ubuntu example:
apt-get install python-setuptools
easy_install pycha
Fedora example:
yum install python-setuptools
easy_install pycha
Benefits: you always get the latest stable version of Pycha. Good
for python veterans.

Option C:
Get a checkout of the subversion trunk branch:
svn co http://www.lorenzogil.com/svn/pycha/trunk pycha
Benefits: this is the bleeding edge version of Pycha. Good for
Pycha developers.


I like the Options section, even when it is far from complete. Keep up
the good work! :-)

One more thing: is there a place where we can grab your documentation
so we can add some changes and send you patches? A
(subversion|mercurial|git|bazar) repository would be great :-)

Best regards

Lorenzo

2009/1/24 Adam <aprzy...@gmail.com>:

[Lorenzo Gil Sanchez]

Hi Adam,

2009/1/28 Adam <aprzy...@gmail.com>:

>
> Hello,
>
> The GTK embedding example is almost finished. I'll update the website
> in a few days.
>
> A few questions about the options:
>
> 1. Are the widths in pixels? For example, the lineWidth default is
> 1.0, so it seems like it's points or mm.

No, they are a Cairo unit. Everything is vector graphics until you
serialize it to a file asuming you use the PNG backend.
See Cairo documentation for more information about this:

http://www.cairographics.org/

>
> 2. There is a 'tickCount' for both axis. It makes sense for the y-
> axis, but does it make sense for the x-tick labels to have a count?
> The number of labels always equals the number of bars, no?
>

Yes if you use BarChart. Not so true with ScatterplotChart or some
other exoteric charts.

> 3. I previously mentioned maybe changing the input method to make it
> more easy. Has there been any discussion of changing how options are
> handled? The problem with the current approach is that it's very easy
> to make mistakes when writing a huge dictionary (missing commas,
> brackets, etc.). It's also very difficult to change just one option
> that's nested deep in the dictionary (user changes the color of bars
> using a gui, for example).
>
> I think it's easier to use attributes:
>
> You can set many options:
> chart.set_yaxis(title = 'X', lineWidth = 1.0, tickCount = 5)
>
> Or just one option:
> chart.set_xaxis(title = 'Y')
>
> You could provide a chart.get_ option method also. This is very useful
> for embedding PyCha in apps.
>

I like your idea as soon as it doesn't add a lot of complexity on the
current code. I'm open to patches that exercise your proposal.


Lorenzo

[Adam Przywecki]

Hey Lorenzo,

I have updated the documentation.

http://pycha.yourwei.com

I'm currently using my little online business website to host it, but
I don't think I can
install subversion on the server (I will check though). Would it be
possible to make a pycha-docs directory in the pycha trunk on your svn
server? I could send you the documentation source tarball. Having the
source code and documentation in one place would be a good idea.

Since some options only apply to some charts, would it make sense to
have chart specific options? For example:

chart.pie.set_yaxis(title = 'pie chart')

chart.scatter.set_yaxis(title = 'scatter plot')

If you're writing a gui app, it would be useful to be able to set the
properties of each chart type (maybe the developer wants different
colors for each chart type).

Finally, is there a timeline for the 0.4.2 release? The 0.4.1 has
quite a few bugs (see tickets) that make it difficult to document/use.
Can we try to close the open tickets that have patches attached? Or at
least discuss the patches.

I think it would be great if we could get phoronix to use pycha for
their phoronix test suite. Their current charts don't look so good :)

Adam

[Lorenzo Gil Sanchez]

Hi Adam,

2009/2/2 Adam Przywecki <aprzy...@gmail.com>:

>
> Hey Lorenzo,
>
> I have updated the documentation.
>
> http://pycha.yourwei.com
>
> I'm currently using my little online business website to host it, but
> I don't think I can
> install subversion on the server (I will check though). Would it be
> possible to make a pycha-docs directory in the pycha trunk on your svn
> server? I could send you the documentation source tarball. Having the
> source code and documentation in one place would be a good idea.

Sure, you can send it to me and I will put it in Pycha repository.

>
> Since some options only apply to some charts, would it make sense to
> have chart specific options? For example:
>
> chart.pie.set_yaxis(title = 'pie chart')
>
> chart.scatter.set_yaxis(title = 'scatter plot')

What does chart.pie means? It doesn't seems clear to me. In this case
just adding methods to the child classes looks more natural to me.

>
> If you're writing a gui app, it would be useful to be able to set the
> properties of each chart type (maybe the developer wants different
> colors for each chart type).
>
> Finally, is there a timeline for the 0.4.2 release? The 0.4.1 has
> quite a few bugs (see tickets) that make it difficult to document/use.
> Can we try to close the open tickets that have patches attached? Or at
> least discuss the patches.
>

Sure, I'm trying to fix the bugs. As I mentioned before, patches in
the form of diff output and test cases would help me to do this task
faster.

Best regards,

Lorenzo

[Adam Przywecki]

Hello,

I have updated the documentation.

http://pycha.yourwei.com

"Chavier" should probably be renamed to "GUI frontend (Chavier)" to make
it more clear what it is.

The source code for the documentation can be downloaded at:

http://pycha.yourwei.com/pycha-docs.tar.bz2

The tarball includes the .build directory which has the html files.

> Sure, I'm trying to fix the bugs. As I mentioned before, patches in
> the form of diff output and test cases would help me to do this task
> faster.

Actually, most of the known bugs have been fixed already. Thanks!

http://www.lorenzogil.com/projects/pycha/ticket/20
http://www.lorenzogil.com/projects/pycha/ticket/25

Both of those tickets have patches. I'll try to get the yvals above bars
to work for horizontal bar charts tonight.

Adam

[Lorenzo Gil Sanchez]

Hi Adam

2009/2/4 Adam Przywecki <aprzy...@gmail.com>:

>
> Hello,
>
> I have updated the documentation.
>
> http://pycha.yourwei.com
>

Nice

> "Chavier" should probably be renamed to "GUI frontend (Chavier)" to make
> it more clear what it is.
>

Note that in the Help menu, About option you get a good description of
what chavier is: a Chart Viewer for Pycha

> The source code for the documentation can be downloaded at:
>
> http://pycha.yourwei.com/pycha-docs.tar.bz2
>
> The tarball includes the .build directory which has the html files.
>

I has added this great docs to the pycha repository. Let me know if
you want an account in such subversion repository so you can keep
working in the docs easily.

[Adam Przywecki]

Hello,

> Note that in the Help menu, About option you get a good description of
> what chavier is: a Chart Viewer for Pycha

I wasn't very clear. I meant changing "Chavier" to something more descriptive in
the documentation index and table of contents.

> I has added this great docs to the pycha repository. Let me know if
> you want an account in such subversion repository so you can keep
> working in the docs easily.

Sure, that would be great. Should I keep hosting the html version on my
site (no problem for me) or will it be added to the main pycha site?

Adam

[Lorenzo Gil Sanchez]

2009/2/5 Adam Przywecki <aprzy...@gmail.com>:

>
>
> Sure, that would be great. Should I keep hosting the html version on my
> site (no problem for me) or will it be added to the main pycha site?

Right now it would be better if you keep hosting the html in your site
until I can set it up in Pycha website.


>
> Adam
>
> >
>