[Pyogp] PJira Issue PYO-3

[Meghan Dench]

Hey folks,

I've Updated PJira Issue PYO-3 ( http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation 'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure

This way all of the 'issues' are separate and can be Updated, assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D

So here's what you guys currently have! In no particular order, other than
Enus at the bottom because he went on Vacation lately, which annoyed me. :P


*Locklainn & Tao:*

You've got PYO-32 ( http://jira.secondlife.com/browse/PYO-32 )


*Tao:*

You've also got PYO-33 ( http://jira.secondlife.com/browse/PYO-33 )

*
Infinity: *

You've got PYO-34 ( http://jira.secondlife.com/browse/PYO-34 )


*Infinity and Enus:*

You've both got

PYO-29 ( http://jira.secondlife.com/browse/PYO-29 )
PYP-35 ( http://jira.secondlife.com/browse/PYO-35 )


*Enus:*

You've got

PYO-28 ( http://jira.secondlife.com/browse/PYO-28 )
PYO-30 ( http://jira.secondlife.com/browse/PYO-30 )
PYO-31 ( http://jira.secondlife.com/browse/PYO-31 )


*You've all got* PYO-36 ( http://jira.secondlife.com/browse/PYO-36 )

*And no one has* PYO-37 ( http://jira.secondlife.com/browse/PYO-37 )


As you work through these please close the individual issues as they're
completed.

Hope you're all well and had good weekends! : )
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.secondlife.com/pipermail/pyogp/attachments/20080729/6d51b133/attachment.htm

[Locklainn]

So, I just committed my UDP message template code (the parser, reader,
builder/serializer). It should be usable for creating and decoding UDP
template messages. Now we just have to write the message system that
will use such things.
Also note that we need a TCP reader/writer for the event queue stuff and
that the previous code doesn't use ZCA. Will have to zca-ify it now that
we have decided to go with it.

Tao,
how exactly does one use your network layer? For instance, how do we
choose which IRESTClient to use? In your test you are just doing
getUtility(IRESTClient), but how do I know if I get urllib2, eventlet,
mock, etc?

Thanks,
Lock

[Christian Scholz]

Hi!

Post by Locklainn
So, I just committed my UDP message template code (the parser, reader,
builder/serializer). It should be usable for creating and decoding UDP
template messages. Now we just have to write the message system that
will use such things.

WOOT! :-)

Post by Locklainn
Also note that we need a TCP reader/writer for the event queue stuff and
that the previous code doesn't use ZCA. Will have to zca-ify it now that
we have decided to go with it.

We can discuss maybe where it makes sense to do so. I don't think we
have to compononentize it just for the fun of it ;-)
But of course it would be cool if you could define the public interfaces
for these classes and put those in message/interfaces.py so it can serve
as documentation.

Post by Locklainn
Tao,
how exactly does one use your network layer? For instance, how do we
choose which IRESTClient to use? In your test you are just doing
getUtility(IRESTClient), but how do I know if I get urllib2, eventlet,
mock, etc?

I think we solved this yesterday. What we both did now was to do
provideUtility(StdLibClient(), IRESTClient)

which tells the framework to use the StdLibClient instance if asked for
an IRESTClient utility. This is not completely correct what we do here
though as such an override should happen more explicit (in this case
it's the default anyway and there should not need to be any overriding
needed and the default should be documented). I will document how to do
it propertly (and change it accordingly) soon. For now this should work.
(The problem here btw would be what should happen if another component
overrides this as well. Then you wouldn't know what is active. For this
the configuration machinery with ZCML has some mechanisms in place to
mark overrides so that when the configuration takes place first the
normal registrations are done and then the overrides. Before that is
done it also checks for conflicts and raises an exception if there is one.)

We should maybe think if there is a use case where you have different
instance of the library with different network layers in one
application. Somehow I doubt it but if there would be such a use case
(or for some other component) then we should think about a general
pattern of how to solve this. So maybe we need some configuration object
for the library with which you initialize the components. But I guess it
would need to be passed at least to the initial agent domain, which then
can pass it along to whatever is instantiated from it.

I guess that might make sense for some tests.

-- Christian

[Christian Scholz]

Hi!

Post by Meghan Dench
I've Updated PJira Issue PYO-3 ( http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation 'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure
This way all of the 'issues' are separate and can be Updated, assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D

It makes at least clearer what the load is so thanks for organizing it! :)

I also discussed with Enus yesterday if we maybe should use Sphinx for
documentation. It is reStructured text based and rather easy to write.
The docs will reside on the filesystem and thus in svn which makes them
also versioned which is good I think.
They can also contain example code in doctest format so that we can even
automatically test the documentation and get informed if it does not
match the code anymore. I think it also might make it easier to stay in
one place and be exported from there. At least for me it makes it more
likely to write documentation as it's also faster than editing a wiki.

Sphinx moreover allows for various output generators like HTML, PDF and
others (maybe there is even a mediawiki extension).

I made a little example here: http://pyogp.net/html

(and btw, there is a docs/ directory in pyogp.lib.base by default anyway
which would ship with the package).

-- Christian

PS: And I registered pyogp.net for having a shortname for my
presentation instead of the wiki link. It redirects there. I hope that's
ok with everybody :)

[Tess Chu]

Zero, have you looked at Sphinx vs. other documentation tools? Do you
have any pointers as to whether it's appropriate for our use? We're
using Oxygen for documentation of OGP.

Thanks,
Tess

Post by Christian Scholz
Hi!

Post by Meghan Dench
I've Updated PJira Issue PYO-3 (
http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation 'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure
This way all of the 'issues' are separate and can be Updated,
assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D

It makes at least clearer what the load is so thanks for organizing it! :)
I also discussed with Enus yesterday if we maybe should use Sphinx for
documentation. It is reStructured text based and rather easy to write.
The docs will reside on the filesystem and thus in svn which makes
them also versioned which is good I think.
They can also contain example code in doctest format so that we can
even automatically test the documentation and get informed if it does
not match the code anymore. I think it also might make it easier to
stay in one place and be exported from there. At least for me it makes
it more likely to write documentation as it's also faster than editing
a wiki.
Sphinx moreover allows for various output generators like HTML, PDF
and others (maybe there is even a mediawiki extension).
I made a little example here: http://pyogp.net/html
(and btw, there is a docs/ directory in pyogp.lib.base by default
anyway which would ship with the package).
-- Christian
PS: And I registered pyogp.net for having a shortname for my
presentation instead of the wiki link. It redirects there. I hope
that's ok with everybody :)

[Christian Scholz]

Hi!

Post by Tess Chu
Zero, have you looked at Sphinx vs. other documentation tools? Do you
have any pointers as to whether it's appropriate for our use? We're
using Oxygen for documentation of OGP.

There is also http://xml.resource.org/ which converts documents written
a la http://www.faqs.org/rfcs/rfc2629.html

E.g. OAuth, XRDS-Simple and the portablcontacts spec are written using
this. An example output is here: http://xrds-simple.net/core/1.0/

(At least I think it's xml2rfc used there. But as it's XML you can also
transfer it to any other format anyway).

What would be cool for commenting would be something like the Djangobook
does though:

http://www.djangobook.com/about/comments/

Unfortunately this seems not to be open source. There are other services
like this out there but I think this one is really quite simple.

The best might be to be able to convert this RFC style format to
something like the djangobook version and it would be even better if
some editor would be included for also incorporating these comments
directly.. But I guess such a solution is not directly available ;-)

Just some brainstorming..

-- Christian

Post by Tess Chu
Thanks,
Tess

Post by Christian Scholz
Hi!

Post by Meghan Dench
I've Updated PJira Issue PYO-3 (
http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation 'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure
This way all of the 'issues' are separate and can be Updated, assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D

It makes at least clearer what the load is so thanks for organizing it! :)
I also discussed with Enus yesterday if we maybe should use Sphinx for
documentation. It is reStructured text based and rather easy to write.
The docs will reside on the filesystem and thus in svn which makes
them also versioned which is good I think.
They can also contain example code in doctest format so that we can
even automatically test the documentation and get informed if it does
not match the code anymore. I think it also might make it easier to
stay in one place and be exported from there. At least for me it makes
it more likely to write documentation as it's also faster than editing
a wiki.
Sphinx moreover allows for various output generators like HTML, PDF
and others (maybe there is even a mediawiki extension).
I made a little example here: http://pyogp.net/html
(and btw, there is a docs/ directory in pyogp.lib.base by default
anyway which would ship with the package).
-- Christian
PS: And I registered pyogp.net for having a shortname for my
presentation instead of the wiki link. It redirects there. I hope
that's ok with everybody :)

_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp

[Christian Scholz]

Hi!

Post by Tess Chu
Zero, have you looked at Sphinx vs. other documentation tools? Do you
have any pointers as to whether it's appropriate for our use? We're
using Oxygen for documentation of OGP.

There is also http://xml.resource.org/ which converts documents written
a la http://www.faqs.org/rfcs/rfc2629.html

E.g. OAuth, XRDS-Simple and the portablcontacts spec are written using
this. An example output is here: http://xrds-simple.net/core/1.0/

See the portablecontacts source here:

http://portablecontacts.googlecode.com/svn/spec/core/1.0/drafts/1/spec.xml

(At least I think it's xml2rfc used there. But as it's XML you can also
transfer it to any other format anyway).

Then again when looking at that source, ReST syntax looks easier ;)

What would be cool for commenting would be something like the Djangobook
does though:

http://www.djangobook.com/about/comments/

Unfortunately this seems not to be open source. There are other services
like this out there but I think this one is really quite simple.

The best might be to be able to convert this RFC style format to
something like the djangobook version and it would be even better if
some editor would be included for also incorporating these comments
directly.. But I guess such a solution is not directly available ;-)

Just some brainstorming..

-- Christian

Post by Tess Chu
Thanks,
Tess

Post by Christian Scholz
Hi!

Post by Meghan Dench
I've Updated PJira Issue PYO-3 (
http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation 'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure
This way all of the 'issues' are separate and can be Updated, assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D

It makes at least clearer what the load is so thanks for organizing it! :)
I also discussed with Enus yesterday if we maybe should use Sphinx for
documentation. It is reStructured text based and rather easy to write.
The docs will reside on the filesystem and thus in svn which makes
them also versioned which is good I think.
They can also contain example code in doctest format so that we can
even automatically test the documentation and get informed if it does
not match the code anymore. I think it also might make it easier to
stay in one place and be exported from there. At least for me it makes
it more likely to write documentation as it's also faster than editing
a wiki.
Sphinx moreover allows for various output generators like HTML, PDF
and others (maybe there is even a mediawiki extension).
I made a little example here: http://pyogp.net/html
(and btw, there is a docs/ directory in pyogp.lib.base by default
anyway which would ship with the package).
-- Christian
PS: And I registered pyogp.net for having a shortname for my
presentation instead of the wiki link. It redirects there. I hope
that's ok with everybody :)

_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp

[Christian Scholz]

Just FYI, URL has changed and docs are updated:

http://pyogp.net/docs/pyogp.lib.base/

-- Christian

Post by Christian Scholz
Hi!

Post by Meghan Dench
I've Updated PJira Issue PYO-3 (
http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation 'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure
This way all of the 'issues' are separate and can be Updated, assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D

It makes at least clearer what the load is so thanks for organizing it! :)
I also discussed with Enus yesterday if we maybe should use Sphinx for
documentation. It is reStructured text based and rather easy to write.
The docs will reside on the filesystem and thus in svn which makes them
also versioned which is good I think.
They can also contain example code in doctest format so that we can even
automatically test the documentation and get informed if it does not
match the code anymore. I think it also might make it easier to stay in
one place and be exported from there. At least for me it makes it more
likely to write documentation as it's also faster than editing a wiki.
Sphinx moreover allows for various output generators like HTML, PDF and
others (maybe there is even a mediawiki extension).
I made a little example here: http://pyogp.net/html
(and btw, there is a docs/ directory in pyogp.lib.base by default anyway
which would ship with the package).
-- Christian
PS: And I registered pyogp.net for having a shortname for my
presentation instead of the wiki link. It redirects there. I hope that's
ok with everybody :)