Re: [Twisted-Python] Questions about adding documentation

[tarjei]

A lot has been said in this discussion but I'll add one thing.
On 07/31/2009 06:32 PM, Reza Lotun wrote:
>> Even if I re-suggested the wiki based documentation, I think it's
>> important to be extra careful on how it's used. One thing I personally
>> hate is projects whose documentation is basically wiki-based, and what
>> you end having is a disconnected set of tips, many out of date, of how
>> to do this and that. It could be OK it it's labeled 'Tipi-wiki' but not
>> 'Documentation' :).
>
> I agree - the wiki shouldn't *replace* the documentation, but the
> reality is I have loads of bookmarks of blog posts and discussions on
> the mailing list, and it'd be nice if I could to go one place to find
> all that type of info. A "recipe" or "cookbook" wiki might be all we
> need, with the ability to comment on each. The Activestate Python
> Cookbook is kinda what I'm thinking about:
> http://code.activestate.com/recipes/langs/python/

What I miss is a comment system related to the API docs so that it is 
possible for beginners and others to add small notes there without 
having to make a ticket, wait for it to be assigned etc.

Apart from that I will just welcome anyone who writes documentation.

Kind regards,
Tarjei



>
>> Alternatively, a separate doc repo with sphinx based doc could be built
>> so that it will allow for collaborative development making clear that is
>> a work in progress and a product with 'releases'. I say a different repo
>> to avoid having to give commit access to code for people who are working
>> on doc,  maybe same repo with different permissions would be better. And
>> I suggest sphinx to a) start from scratch and add existing doc as we see
>> it's relevant, b) have a more flexible base than HTML docs, and for the
>> reasons mentioned by Kevin (plus I want to learn it :P).
>
> I haven't yet looked at lore or sphinx, but is there a way to support
> sphinx via lore?
>
> Reza
>


-- 
Tarjei Huse
Mobil: 920 63 413

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Questions about adding documentation

[Michael Hudson]

2009/8/3 tarjei :
> A lot has been said in this discussion but I'll add one thing.
> On 07/31/2009 06:32 PM, Reza Lotun wrote:
>>> Even if I re-suggested the wiki based documentation, I think it's
>>> important to be extra careful on how it's used. One thing I personally
>>> hate is projects whose documentation is basically wiki-based, and what
>>> you end having is a disconnected set of tips, many out of date, of how
>>> to do this and that. It could be OK it it's labeled 'Tipi-wiki' but not
>>> 'Documentation' :).
>>
>> I agree - the wiki shouldn't *replarce* the documentation, but the
>> reality is I have loads of bookmarks of blog posts and discussions on
>> the mailing list, and it'd be nice if I could to go one place to find
>> all that type of info. A "recipe" or "cookbook" wiki might be all we
>> need, with the ability to comment on each. The Activestate Python
>> Cookbook is kinda what I'm thinking about:
>> http://code.activestate.com/recipes/langs/python/
>
> What I miss is a comment system related to the API docs so that it is
> possible for beginners and others to add small notes there without
> having to make a ticket, wait for it to be assigned etc.

I have an old, half finished idea in this area, which is that pydoctor
has a mode which runs a web server and allows you to edit the
docstrings online.  It needs a bunch of work to get to useful --
probably user accounts, a way of not losing all changes when you
restart the server, a lot of polish and, indeed, maybe a comment
feature or discussion view -- but I think the idea is sound.

If you have pydoctor installed, you can try pydoctor --auto in a
directory containing some python modules.

Cheers,
mwh

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Questions about adding documentation

[listsin]

On Aug 2, 2009, at 12:41 AM, Glyph Lefkowitz wrote:

On Sat, Aug 1, 2009 at 11:30 PM, Steve Steiner (listsin) > wrote:

Where would we put an "inventory" project for it to be most useful?

 As JP mentioned earlier in this thread, some work has already  
taken place here: .


It doesn't really look like that effort went anywhere.

I don't think it's quite fair to say it didn't go anywhere, it just  
didn't get anywhere particularly complete.  I think the reviews that  
have been done thus far are still a valuable resource for someone  
interested in working on the documentation.


Ok, fine, it went "over there."  Now...if you're just starting out,  
how much does "over there" help and how much has "over there" ever  
been integrated into anything else?  How would you even find "over  
there?"


I guess I'm still frustrated with the lack of an overarching doc  
organization scheme.


I've tried to use various parts of the Twisted eco-system, on a number  
of projects, and have repeatedly gotten stuck on outdated, disjointed,  
disorganized, and just plain wrong documentation.


As I've said before, the complete lack of date/version stamping on  
example code has been the greatest source of frustration.


I've, more than once, gotten half-way through a tutorial and realize  
that it just plain didn't work with the current version.


End of exploration.

I used the best result I found in my search and it just didn't work.   
Gotta move on; client's getting annoyed.  Unbillable time; bad.


What we really need is for people in the community to knuckle down  
and do the work of actually reviewing the documents, rewriting  
things, soliciting feedback, copy-editing the documents, checking  
for accuracy, etc.  As Jessica did when she started the thread :).


Hasn't happened, and isn't going to happen, in my opinion, until  
there's some actual incentive for "people in the community", which is  
a small subset of the "potential community", to actually do anything  
about it.  Documentation is not needed by the "community" as much as  
it's needed by the "potential community."


Frankly, the work is boring: what the documentation needs is not a  
dynamic market-driven system for managing contributions and paying  
bounties, it's not a comprehensive overhaul of our entire  
documentation toolchain.  What it needs is for people to sit down  
and read all the documentation, make a list of all of its problems,  
one at a time, and then write, delete, and edit as necessary,  
incorporating feedback from the community.


Frankly, the work is boring and it ain't happening, never has, and  
never will unless something changes.  Bounty system, torture, Target  
coupons, whatever...


Once we have people taking part in that effort and working with the  
docs on a daily or weekly basis, then we can listen to the reality  
of the problems and frustrations that they have working with the  
tools or determining priorities or whatever and solve those problems.


See above.  How many years does the same thing have to happen for  
there to be a realization that, without a fundamental change, nothing  
is going to happen?


If you paid someone, 20 hours a week, to babysit the documentation  
effort, they would.  Depending on their competence, there would be  
progress.


If you wait, endlessly for "Once we have people taking part in that  
effort and working with the docs on a daily or weekly basis", you're  
going to get the same result.


Separately from that, if you're interested in contributing some time  
to manage a bounty program for the TSF, that might be a reasonable  
idea.  Other projects have experimented with bounty-based systems  
for resolving bugs.  Unfortunately there are a number of  
difficulties with those systems, which are really out of the scope  
of this discussion, but they're worth talking about if you have a  
real interest in doing it.


I'm not sure what I'm interested in, at this point, but I certainly am  
not interested in doing it for free and neither is anyone else.


In my opinion, and by existing evidence, coherent documentation ain't  
happening, and won't, unless something fundamental changes.


It's not my project and it's not for me to decide but it seems to me  
that waiting for "people to take part in that effort" is doomed to  
waiting forever...


S

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Twisted-Python] Twisted.web.client.getPage with proxy?

[disappearedng]

Hello world,
1) I have a proxy server running on my computer on port . It's
listening on localhost.
I am wondering whether Twisted.web.client.getPage has some sort of
proxy kwargs that can do this for me. ( I checked the source and I
really doubt it has something like that)
What are my alternatives? I have looked at low-level alternatives, and
ProxyClient doesn't really seem to fit my situation.

2) I sometimes have 2 proxy servers running. I know urllib has a
method which allows you to build opener, then you can access webpages
with opener.open('site').read().
Does twisted have something like this which allows me to keep multiple
"proxy space" to access different websites at the same time on
different proxy servers?

Thx

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Deferred documentation rewrite

[Edward Z. Yang]

I have updated my draft here:

http://ezyang.com/twisted/defer2.html

The most notable change is I've removed the section "From Synchronous to
Asynchronous".  I believe (and I think other people agree with me) that
this is an important topic to cover, but it's really *hard* to teach
asynchronous programming and I'd like to think a bit more about how I'd
like to frame the subject.  There are at least two issues that we have
to deal with:

* Why asynchronous?
- Define synchronous and asynchronous
- Multiplexing IO
- Introduce a simple reactor based on select()
* Why callbacks?
- Asynchronous interaction to synchronous interaction
- Delocalized execution (the parser example)
- High level functions in Python review

Quite frankly, I'm stumped on "defining synchronous and asynchronous."
Asynchronous had always made sense to me, coming from JavaScript, since
it was "you click this button and something should happen!"  But that
is a very different use-case of asynchronous programming than Twisted is.
And Glyph raised some very salient concerns about what we were trying to
teach people.  I just don't know what direction people are coming from.

As such, the document now is targeted to "people who know the basics
of asynchronous programming and grok callbacks", and I've incorporated
Itamar's excellent suggesting of comparing explicit callback parameters
and the Deferred object, which I hope dispells the notion of Deferred
being magical fairly well (my assertion is Deferred is merely an
abstraction over said callback parameters.)  I've also fully fleshed
out the Deferreds reference; any omissions are my fault.

The plan next is to discuss composing deferreds (which will also
touch on when you should and how to create your own deferreds, as
well as deferredlist) and the convenience primitives.

Cheers,
Edward

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Deferred documentation rewrite

[Dave Britton]

- Original Message -
From: "Edward Z. Yang" 
To: "Twisted general discussion" 
Sent: Monday, August 03, 2009 6:00 PM
Subject: Re: [Twisted-Python] Deferred documentation rewrite

I like the side-by-side regular and twisted versions,  that's helpful.
You are approaching the complicated stuff toward the end - please don't stop
there.
Show some more examples of more intricate cases of side-by-side logic,
eg how to use deferreds for this if all foo's are asynchronous:
x=foo1(y)
if x > 0:
z=foo2(x)
y = foo3(z)
else:
z=foo4(x,y)
alldone=foo5(z)
# now add error handling for all the deferreds
# how would I debug things if foo3 had an unanticipated error?

My latest real question for the docs to answer is,
Are these different?
== example 1 
d=asynchronousprocess()
d.addCallback(b)
d.addCallback(c)
d.addErrback(errbc)
=== example 2 
d=asynchronousprocess().addCallback(b).d.addCallback(c).d.addErrback(errd)
=
Why or why not? When might one use one form over the other?
-Dave


___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Twisted-Python] twisted.positioning preliminary review

[Laurens Van Houtven]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Hey :-)



I've been told that I need to produce a patch faster, and most of the
eyesores that I was really unhappy with have been removed (no more
mutable sentenceData dict \o/). As usual, comments welcome.

I could produce an actual patch, but perhaps it would be more useful
to do this with the Launchpad-published bzr branch? Obviously that
means I can't attach a real patch to a trac ticket. If people want me
to, I will.

Some of the obvious problems that I've seen myself or that come up on
the mailing list are tagged with "REVIEW", so if you only have 10
minutes to look at it, grep nmea.py for it :-)

Obvious TODO is howto documentation, but I'm not starting on that
until the API has been reviewed thoroughly for obvious reasons.


Here it is: http://bit.ly/3wWL2c

Or you could just: bzr branch lp:~lvh/twisted/positioning



Thanks for your time
Laurens
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Use GnuPG with Firefox : http://getfiregpg.org (Version: 0.7.8)

iEYEARECAAYFAkp3hvsACgkQT5v5zGkvKT4vTwCdG41LE0snM8vdK1L9ohF8wZRo
+T4An2RQz22QmjT1YFEAmOT8IHJyoT8C
=WbHv
-END PGP SIGNATURE-

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] twisted.positioning preliminary review

[Glyph Lefkowitz]

On Mon, Aug 3, 2009 at 8:56 PM, Laurens Van Houtven wrote:


> I could produce an actual patch, but perhaps it would be more useful
> to do this with the Launchpad-published bzr branch? Obviously that
> means I can't attach a real patch to a trac ticket. If people want me
> to, I will.


The ticket is currently pending review, so when someone has some time for
Twisted reviews, you should get some feedback on it.  You might want to
attach a comment that makes it very clear for a reviewer where the code
actually is, since the ticket seems to have begun its life in the 'review'
state; it's a bit unorthodox for someone to keep working on a ticket once
it's been submitted for review.  The normal workflow is to have the comment
that attaches the 'review' keyword be the submission for review, and the
comment that removes it be the review commentary.  (Or something close to
that, trac's UI is so hard to drive.)

We've got a bit of a review backlog right now so there may be some latency
:-\.  Perhaps you should volunteer to review some tickets yourself? :)

The way to get from your launchpad branch to the relevant SVN-like diff is
this:

bzr get lp:~lvh/twisted/positioning positioning-3926
cd positioning-3926
bzr diff -r ancestor:lp:twisted

Attaching this patch to the ticket may make  a reviewer's life easier; not
everyone is equally facile with bzr.


> Some of the obvious problems that I've seen myself or that come up on
> the mailing list are tagged with "REVIEW", so if you only have 10
> minutes to look at it, grep nmea.py for it :-)
>
> Obvious TODO is howto documentation, but I'm not starting on that
> until the API has been reviewed thoroughly for obvious reasons.
>

This can be a separate ticket.

Here it is: http://bit.ly/3wWL2c
>
> Or you could just: bzr branch lp:~lvh/twisted/positioning
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python