Re: [Twisted-Python] Refactoring Documentation

On Sun, Jan 23, 2011 at 2:08 AM, Glyph Lefkowitz wrote: > > On Jan 23, 2011, at 12:55 AM, Tom Davis wrote: > > > But I'm drifting now, so shall drift in the direction of bed and pick > things up tomorrow... > > I think this thread has reached a nice point of consensus, so rather than > keep floodi

Re: [Twisted-Python] Refactoring Documentation

On Jan 23, 2011, at 12:55 AM, Tom Davis wrote: > But I'm drifting now, so shall drift in the direction of bed and pick things > up tomorrow... I think this thread has reached a nice point of consensus, so rather than keep flooding everybody's inboxes with 'me too', I'm going to withdraw until

Re: [Twisted-Python] Refactoring Documentation

On Sat, Jan 22, 2011 at 10:02 PM, Glyph Lefkowitz wrote: > > On Jan 22, 2011, at 3:18 PM, Tom Davis wrote: > > On Fri, Jan 21, 2011 at 10:00 PM, Glyph Lefkowitz > wrote: > >> On Jan 20, 2011, at 11:20 PM, Tom Davis wrote: >> >> If branches that are out there *don't* meet these standards, commenti

Re: [Twisted-Python] Refactoring Documentation

On Jan 22, 2011, at 3:18 PM, Tom Davis wrote: > On Fri, Jan 21, 2011 at 10:00 PM, Glyph Lefkowitz > wrote: > On Jan 20, 2011, at 11:20 PM, Tom Davis wrote: > > If branches that are out there don't meet these standards, commenting on > their tickets and getting them deleted or closed as invali

Re: [Twisted-Python] Refactoring Documentation

On Fri, Jan 21, 2011 at 10:00 PM, Glyph Lefkowitz wrote: > On Jan 20, 2011, at 11:20 PM, Tom Davis wrote: > > I definitely agree that resolving the low-hanging fruit first is a good > idea. For finishing "docs branch X" to make sense, my personal belief is > that X should: > >- Still be releva

Re: [Twisted-Python] Refactoring Documentation

On 03:00 am, gl...@twistedmatrix.com wrote: >>Finally, my biggest hurdle right now is not knowing how to find said >>branches. I don't see "documentation" as a category in Trac and common >>keyword searches didn't show up much for me. I'm sure this is an easy >>question to answer, though. > >

Re: [Twisted-Python] Refactoring Documentation

On Jan 20, 2011, at 11:20 PM, Tom Davis wrote: > I definitely agree that resolving the low-hanging fruit first is a good idea. > For finishing "docs branch X" to make sense, my personal belief is that X > should: > Still be relevant in terms of best practices and simply what's available > If pro

Re: [Twisted-Python] Refactoring Documentation

I have a lot of input here, but as the guys actually doing the work, the final say is mostly with you and Tom. So, please feel free to take everything here with a grain of salt. On Jan 20, 2011, at 2:58 PM, Kevin Horn wrote: > Here's some things I had "planned" (yes, I'm using the term loosely

Re: [Twisted-Python] Refactoring Documentation

On Jan 20, 2011, at 7:43 PM, Kevin Horn wrote: > It could even use Lore's parser, twisted.lore.tree.parseFileAndReport ;) > > Jean-Paul > > > Yes, but: > > - The docs (well, docstrings) aren't very clear about exactly what that does, > or what quirks it might or might not have. The source

Re: [Twisted-Python] Refactoring Documentation

On Jan 20, 2011, at 1:54 PM, Kevin Horn wrote: > The biggest problem with this is that you will find that a very small group > of people have created the vast majority of this stuff and don't have time to > maintain it all any more :). We certainly don't have a separate dedicated > maintainer

Re: [Twisted-Python] Refactoring Documentation

> On 21 January 2011 22:35, Glyph Lefkowitz wrote: >> �I don't believe we have a mirror on >> github, but maybe somebody could correct me. > > There are 79 repos on github that match the word twisted. > > This one claims to be updated every 15 minutes and seems to be pretty > up to date (has a com

Re: [Twisted-Python] Refactoring Documentation

On 21 January 2011 22:35, Glyph Lefkowitz wrote: >  I don't believe we have a mirror on > github, but maybe somebody could correct me. There are 79 repos on github that match the word twisted. This one claims to be updated every 15 minutes and seems to be pretty up to date (has a commit from 13

Re: [Twisted-Python] Refactoring Documentation

On Fri, Jan 21, 2011 at 5:35 PM, Glyph Lefkowitz wrote: > > On Jan 21, 2011, at 8:29 AM, exar...@twistedmatrix.com wrote: > > I don't think it makes sense to put anything on Launchpad for now. > Eventually it needs to go into the canonical Twisted repository, but if > it's easier to leave it in Gi

Re: [Twisted-Python] Refactoring Documentation

On Jan 21, 2011, at 8:29 AM, exar...@twistedmatrix.com wrote: > I don't think it makes sense to put anything on Launchpad for now. > Eventually it needs to go into the canonical Twisted repository, but if > it's easier to leave it in GitHub for now, that's fine. The only reason I even suggeste

Re: [Twisted-Python] Refactoring Documentation

On 04:20 am, t...@recursivedream.com wrote: >Finally, my biggest hurdle right now is not knowing how to *find* said >branches. I don't see "documentation" as a category in Trac and common >keyword searches didn't show up much for me. I'm sure this is an easy >question to answer, though. http://twi

Re: [Twisted-Python] Refactoring Documentation

Wow! Okay, so, not being really familiar with the list etiquette combined with the fact that the topic has digressed a bit, I hope you'll forgive the non-inline reply here. I want to hit the main points of what everybody said / asked, but let it be known that I read all of it! How can we combine t

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 06:34:17PM -0600, Kevin Horn wrote: > On Thu, Jan 20, 2011 at 5:57 PM, Tim Allen wrote: > > You mean these DTDs? > > > >twisted/lore/xhtml1-strict.dtd > >twisted/lore/xhtml1-transitional.dtd > > > > They reference the xhtml-*.ent entity definitions which are also in

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 6:06 PM, wrote: > On 20 Jan, 11:57 pm, screwt...@froup.com wrote: > >On Thu, Jan 20, 2011 at 05:22:55PM -0600, Kevin Horn wrote: > >>Hmmm...yes, I think it does. It looks like the l2s_builder script is > >>choking on fetching the DTD for some reason. lore2sphinx itself i

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 5:57 PM, Tim Allen wrote: > On Thu, Jan 20, 2011 at 05:22:55PM -0600, Kevin Horn wrote: > > Hmmm...yes, I think it does. It looks like the l2s_builder script is > > choking on fetching the DTD for some reason. lore2sphinx itself is > supposed > > to cache the DTD between

Re: [Twisted-Python] Refactoring Documentation

On 20 Jan, 11:57 pm, screwt...@froup.com wrote: >On Thu, Jan 20, 2011 at 05:22:55PM -0600, Kevin Horn wrote: >>Hmmm...yes, I think it does. It looks like the l2s_builder script is >>choking on fetching the DTD for some reason. lore2sphinx itself is >>supposed >>to cache the DTD between runs, but

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 05:22:55PM -0600, Kevin Horn wrote: > Hmmm...yes, I think it does. It looks like the l2s_builder script is > choking on fetching the DTD for some reason. lore2sphinx itself is supposed > to cache the DTD between runs, but I'm betting it doesn't work in the > buildbot due t

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 4:45 PM, wrote: > On 10:05 pm, kevin.h...@gmail.com wrote: > >On Thu, Jan 20, 2011 at 1:55 AM, Glyph Lefkowitz > >wrote: > >> > >>(I was going to point you at the output of the buildbot, but it looks > >>like > >>something in trunk has broken the conversion process. Anyon

Re: [Twisted-Python] Refactoring Documentation

On 10:05 pm, kevin.h...@gmail.com wrote: >On Thu, Jan 20, 2011 at 1:55 AM, Glyph Lefkowitz >wrote: >> >>(I was going to point you at the output of the buildbot, but it looks >>like >>something in trunk has broken the conversion process. Anyone know >>what this >>is about? < >>http://buildbot.tw

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 1:55 AM, Glyph Lefkowitz wrote: > > (I was going to point you at the output of the buildbot, but it looks like > something in trunk has broken the conversion process. Anyone know what this > is about? < > http://buildbot.twistedmatrix.com/builds/sphinx-html-15724/contents.

Re: [Twisted-Python] Refactoring Documentation

I alluded in my earlier mail to some of the improvement ideas I have had regarding Twisted's docs (other than the conversion to Sphinx), and I though I'd elaborate Here's some things I had "planned" (yes, I'm using the term loosely) to try and add/improve/fix in the Twisted docs after the Sphinx c

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 1:55 AM, Glyph Lefkowitz wrote: > Let me begin by saying that I'm _very_ excited about this prospect and I'm > looking forward to the output of this project. So, some of what I'm about > to say may sound like harsh criticism but *please do not let it discourage > you*. I

Re: [Twisted-Python] Refactoring Documentation

Hear! Hear! My major disappointment with Twisted is its documentation. I've used many many packages over the years, some with books and books of documentation (HP OpenView, e.g.), but I've never encountered a package with poorer help for a newbie. I finally started to get it when I stumbled upon

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 2:55 AM, Glyph Lefkowitz wrote: > (minor nitpick: I really like "event-based" or "event-driven", as you've > said here: why does say > "asynchronous"? I find that especially in documentation it's a lot easier to > explain "event-dri

Re: [Twisted-Python] Refactoring Documentation

Let me begin by saying that I'm _very_ excited about this prospect and I'm looking forward to the output of this project. So, some of what I'm about to say may sound like harsh criticism but please do not let it discourage you. I agree with pretty much everything you're saying about problems w

Re: [Twisted-Python] Refactoring Documentation

On Thu, Jan 20, 2011 at 12:10 AM, Tom Davis wrote: > I've been using (and threatening to work on) Twisted for a few years now. > It seems like every time I get back into it, I need to dig up old code or > Google queries just to get started. Yesterday, Jean-Paul introduced me to > the trial-tutori

[Twisted-Python] Refactoring Documentation

I've been using (and threatening to work on) Twisted for a few years now. It seems like every time I get back into it, I need to dig up old code or Google queries just to get started. Yesterday, Jean-Paul introduced me to the trial-tutorial branch