<div dir="ltr">On Fri, Mar 1, 2013 at 4:15 PM, Glyph <span dir="ltr">&lt;<a href="mailto:glyph@twistedmatrix.com" target="_blank">glyph@twistedmatrix.com</a>&gt;</span> wrote:<br><div class="gmail_extra"><div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><br><div><div>On Mar 1, 2013, at 9:44 AM, Kevin Horn &lt;<a href="mailto:kevin.horn@gmail.com" target="_blank">kevin.horn@gmail.com</a>&gt; wrote:</div>
<br><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr">On Fri, Mar 1, 2013 at 2:29 AM, Glyph<span> </span><span dir="ltr">&lt;<a href="mailto:glyph@twistedmatrix.com" target="_blank">glyph@twistedmatrix.com</a>&gt;</span><span> </span>wrote:<br>
<div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word">
Jean-Paul recently closed a Lore ticket as invalid, and suggested we have a discussion about Lore&#39;s future direction.  This strikes me as a very good idea, and so I wrote a message which is a bit too long (for which I apologize) to kick that off.<div>
<br></div><div><div>I don&#39;t think these two paths (lore2sphinx and continuing to maintain lore) are necessarily mutually exclusive.  Also I think it implies something about the current state of affairs that isn&#39;t accurate - e.g. that the Twisted team has agreed that Sphinx will surely replace Lore and that we are making progress on that process of placement more than we are maintaining Lore itself.<br>
</div><div><br></div><div>Unfortunately, I think it will be clear to anyone following its progress that lore2sphinx is unmaintained and the sphinx migration effort is stalled.  Nobody has committed to &lt;<a href="https://bitbucket.org/khorn/lore2sphinx" target="_blank">https://bitbucket.org/khorn/lore2sphinx</a>&gt; in a year and a half, about the same amount of time that &lt;<a href="http://twistedmatrix.com/trac/browser/branches/sphinx-conversion-4500" target="_blank">http://twistedmatrix.com/trac/browser/branches/sphinx-conversion-4500</a>&gt; has been idle as well.  By contrast, &lt;<a href="http://twistedmatrix.com/trac/browser/trunk/twisted/lore" target="_blank">http://twistedmatrix.com/trac/browser/trunk/twisted/lore</a>&gt; has seen commits - albeit not many - within only a couple of weeks.  So, empirically, we&#39;re already maintaining lore and lore2sphinx is currently &quot;obsolete&quot;; really the question should be if we want to reverse that path.</div>
<div><br></div></div></div></blockquote><div><br></div><div>Some what orthagonal to your point, but this is incorrect.  lore2sphinx was split some time ago into &quot;lore2sphinx-ng&quot; and &quot;rstgen&quot;.</div></div>
</div></div></div></blockquote><div><br></div><div>Hi Kevin!  Long time no see!  (Too long, obviously!)</div><br><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px">
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><a href="https://bitbucket.org/khorn/lore2sphinx-ng" target="_blank">https://bitbucket.org/khorn/lore2sphinx-ng</a><br></div><div><a href="https://bitbucket.org/khorn/rstgen" target="_blank">https://bitbucket.org/khorn/rstgen</a><br>
</div><div><br></div><div>This was initially done as an experiment in using a more explicit &quot;formatting model&quot; for the generation for the Sphinx docs (and somewhat due to _your_ prodding, Glyph), and so I didn&#39;t initially make a big announcement or anything.</div>
</div></div></div></div></blockquote><div><br></div><div>I do remember this.  The previous output of lore2sphinx really was unreliable enough that it was creating a never-ending treadmill of irrelevant / unpredictable Lore source fixes that were really dragging the whole process out.  Thanks for working on improving it.</div>
<br></div></div></blockquote><div><br></div><div style>That &quot;never-ending&quot; series of Lore source fixes took place over the course of a couple of weeks.  Doing things that way was not my idea, though it seemed reasonable at the time because  the idea was that we would do the cutover at the end of it.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><blockquote type="cite">
<div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>Once it became apparent that it was actually going to work out better, I sent out some emails to those who had expressed interest in helping with the whole lore2sphinx project, though I don&#39;t believe I sent out anything to the twisted list in general, as I probably should have.  I&#39;ll point out that I can count people who have shown interest in moving this forward on one hand, though.</div>
</div></div></div></div></blockquote><div><br></div><div>More discussion on this list would be almost always be better.  We are a *long* way from too much traffic here.  (And, this update is honestly a surprise to me.)</div>
<br><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>
<div>And I&#39;ve specifically mentioned that I had done said forking to you, Glyph, in IRC  ;)</div><div>(though it&#39;s IRC after all...who remembers what happens in IRC?)</div></div></div></div></div></div></blockquote>
<div><br></div><div>Based on this exchange, my understanding was simply that you had started to try to improve lore2sphinx, but then wandered off again.</div><br></div></div></blockquote><div><br></div><div style>I never &quot;wandered off&quot;.  Been here the whole time.  I&#39;ve been in #twisted almost continually for about the last 3 years, and in #twisted-dev for about a year (I didn&#39;t relaize it existed before that). I just got tired of (my perception) talking to myself about doing the conversion.  So I was being quiet.  Granted, I shouldn&#39;t have been, and that&#39;s on me.  but it&#39;s not like I&#39;m hard to get a hold of.</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><blockquote type="cite">
<div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>I thought I had put a notice up in the readme file in the lore2sphinx repo, but as it isn&#39;t there, I presume I either forgot, or never got it merged, or something.</div>
<div><br></div><div>So, totally my bad for not communicating better, but I have NOT given up on converting things from Lore into Sphinx.<br></div><div>(Nor do I intend to.)</div></div></div></div></div></blockquote><div><br>
</div><div>OK.  Let&#39;s move things along then.  </div></div></div></blockquote><div><br></div><div style>Yes lets.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><div>Several people showed up on IRC yesterday and voiced an interest in helping out, although what to do next - especially what to do next for a new contributor who does *not* want to try to reverse-engineer the conversion itself - needs to be made much, much clearer.</div>
<br></div></div></blockquote><div><br></div><div style>The last day or two have probably not been the best to try and get my attention, especially yesterday, as I essentially worked a 14 hr day trying to meet a deadline. But I see the conversation on IRC.  I&#39;ll note that noone seems to have considered asking me anything about it.  Looks like it was about 4am, though, so perhaps that wouldn&#39;t have done much good, as I was asleep. :) </div>
<div style><br></div><div style>But hey...I have email!  Ask me!  I&#39;ll talk your ear off about it!</div><div style><br></div><div style>(As an aside, lore2sphinx is in no way a &quot;broken pile of regexes&quot;.  Not to say that it isn&#39;t broken in some really significant ways, because it is, but it doesn&#39;t use regexes at all.  Just sayin&#39;.)</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><blockquote type="cite">
<div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>Thinking about it, I suppose I&#39;ve been somewhat reticent to do much communicating about any work I do on this, as what seems to happen is that it just gives everyone an excuse bring up some new objection to actually getting the conversion done.  I hadn&#39;t really realized this consciously until just now, though.</div>
</div></div></div></div></blockquote><div><br></div><div>Communicate constantly.  The biggest objection that _I_ have to getting the conversion done at this point is that the people working on it (well, okay: you) are uncommunicative, unreliable and frequently unavailable. ;-)  If you were just keeping us all up to date - even just to complain! - I&#39;d be much more sanguine about the whole thing.  And apparently some of your misconceptions would have been corrected a lot earlier.</div>
<br></div></div></blockquote><div><br></div><div style>I got tired of complaining.  And arguing. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word">
<div></div><div>I also have no objection if someone wants to complete the lore2sphinx work, but if the lore2sphinx buildbot were to die tomorrow and go offline, I wouldn&#39;t be particularly anxious to spend a lot of resources to fix it.</div>
<div><br></div><div>My position on this was always that if someone wanted to improve the documentation, they were welcome to do so, and if they wanted to use Sphinx to do it, that&#39;s great too.  I just wasn&#39;t willing to tolerate any period where our toolchain was broken and we couldn&#39;t generate documentation for a release.  And a good thing we didn&#39;t, by the way!  If we had said &quot;go ahead, pull the trigger, whatever, it&#39;s OK to break trunk for a little while!&quot; we wouldn&#39;t have had any documentation toolchain for the last 2 years.</div>
<div><br></div></div></blockquote><div><br></div><div>And since we didn&#39;t break the toolchain, I&#39;ve been in no particular hurry.  I&#39;ve accepted that this will take approximately a billion years.  So no rush.</div>
</div></div></div></div></blockquote><div><br></div><div>It does not have to take a billion years.  The criteria ought to be clear - and if they aren&#39;t, you should have asked for clarification :).</div><br></div></div>
</blockquote><div><br></div><div style>I have asked for clarification more times than I can count about more aspects of this than I can possibly keep track of. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div>On the other hand, I have at several points been willing to make the &quot;cutover&quot;, and for various different reasons, been told it wasn&#39;t happening until things were closer to &quot;perfect&quot; (for some value of &quot;perfect&quot;) than they were at the time.</div>
</div></div></div></div></blockquote><div><br></div><div>Let&#39;s be specific: &lt;<a href="http://twistedmatrix.com/trac/ticket/5312" target="_blank">http://twistedmatrix.com/trac/ticket/5312</a>&gt; is in need of some final code-review.  Despite several reviews and an apparently extensive final response pass, it&#39;s not currently in review, which means it&#39;s still in your court for some reason.  There is no reason to hold back on this and try to do *everything* in one big bang: this code just needs to be production-quality and land on trunk _before_ the ReST sources themselves are ready to go.</div>
<div><br></div></div></div></blockquote><div><br></div><div style>Despite numerous attempts to prod someone into responding to my requests for clarification ;) on the ticket, I never got any response.  Specifically, I could never get an answer on whether the sphinx build tool should require whomever was running it to specify a version or whether the tool should guess.  The existing tools (at the time, I haven&#39;t looked at the current state of these) do/did both, in different places.</div>
<div style><br></div><div style>And I admit, my impetus for immediacy kind of crashed when I had spent several weeks (I thought) getting everything ready to switch over the docs (in 4500) and then being told &quot;oh we have some release stuff, we need to have a tool for that too&quot;.  My impression prior to this was that sphinx-build would be used to build the sphinx docs, which turned out to be erroneous.  I didn&#39;t even know that those tools (twisted.python._release) even existed prior to that point.</div>
<div style><br></div><div style>Anyway, after a while it looked like fixing the lore sources would have to be done all over again, so I started looking into whether the conversion process itself could be improved, so that we didn&#39;t have to keep doing that.</div>
<div style><br></div><div style>Also, please elaborate on what you mean  by &quot;do *everything* in one big bang.  My intention was never to do anything but get the SphinxBuilder working on that branch.  Was there something else you thought I was doing?  Was there something else I should (or should not) have been doing?</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div></div>
<div>Probably something needs to happen to the buildbot build steps, too, since there&#39;s this nastiness that did an end-run around our development process to get checked in to the buildbot config without tests instead of into twisted with tests, &lt;<a href="http://buildbot.twistedmatrix.com/builders/documentation/builds/2994/steps/process-docs/logs/stdio" target="_blank">http://buildbot.twistedmatrix.com/builders/documentation/builds/2994/steps/process-docs/logs/stdio</a>&gt;, and that needs to be replaced with a command that&#39;s just like &quot;build the docs, whether they be lore or sphinx or docbook or whatever&quot;.  But, Tom&#39;s got your back here; if you can get this done during his fellowship (see today&#39;s post, &lt;<a href="http://labs.twistedmatrix.com/2013/03/welcome-our-new-twisted-fellow-tom.html" target="_blank">http://labs.twistedmatrix.com/2013/03/welcome-our-new-twisted-fellow-tom.html</a>&gt;) I estimate you will see a completed reconfiguration within hours.</div>
</div></div></blockquote><div><br></div><div style>I have no idea about how the buildbots are configured.  But the linked buildbot log looks like part of the official release process.</div><div style><a href="http://twistedmatrix.com/trac/wiki/ReleaseProcess#Buildhowtodocumentsforwebsite">http://twistedmatrix.com/trac/wiki/ReleaseProcess#Buildhowtodocumentsforwebsite</a><br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div>
</div><div>Once that&#39;s done, then it&#39;s a matter of putting &lt;<a href="http://tm.tl/4500" target="_blank">http://tm.tl/4500</a>&gt; into code-review with the output of the lore2sphinx builder.  That review can be somewhat expedited, and can be done in parallel by lots of people since there are no unit tests to be worried about, and formatting fixes can be done quickly by multiple people, we don&#39;t need a big formal code review.</div>
<br><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>
The current output of the old lore2sphinx branch is functional, though has a few warts (mostly extraneous spaces in the output).  These warts were apparently enough to block adoption.</div></div></div></div></div></blockquote>
<div><br></div><div>Let&#39;s not under-state the problem: thanks to the jaw-droppingly weird arbitrariness of the ReST format, &quot;extraneous spaces&quot; can mean &quot;arbitrarily mangled output&quot;.  But no, even these &quot;warts&quot; were not enough to block adoption.  What blocked adoption is that the painstakingly hand-tweaked lore sources that did <i>not </i>have any more &quot;warts&quot; were left to languish (and bit-rot, and now probably require more manual fixing) while we waited for 2 years for someone to actually finish the sphinx development and release management tools and get them finalized.  As I recall we basically finished fixing them all up, at the time.</div>
</div></div></blockquote><div><br></div><div style>They got left alone because of the release tools hangup.  Ideally the release tools would have been done before the whole lore-source-tweaking process, but they weren&#39;t.  I&#39;ll admit my frustration played a part in this, but so did the deafening silence I got when I asked for anyone to comment on the ticket.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div></div>
<div>There were three reasons that I personally kept pressing for a more thorough lore -&gt; sphinx converter.  One is not necessarily necessary.</div><div><br></div><div>First, and most importantly, is the bit-rot problem: people are working on lore docs in parallel with this effort.  And, despite this exchange, I want to be clear that they should keep doing so: nobody should stop working on docs in the meanwhile, since we have no way to tell how much longer this will take.  Looking at the modified docs on the sphinx buildbot is challenging, and keeping track of random whitespace jiggling is not documented on &lt;<a href="http://twistedmatrix.com/trac/wiki/ReviewProcess#Reviewers:Howtoreviewachange" target="_blank">http://twistedmatrix.com/trac/wiki/ReviewProcess#Reviewers:Howtoreviewachange</a>&gt;.  *I* can&#39;t even remember how to do the math to associate one of the results in &lt;<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html/</a>&gt;.  And now that there have been so many changes (as I predicted there might be) we have to figure out what&#39;s changed, and re-review to make sure that everything (or at least a big enough majority of everything) is OK to go to trunk.  If the tool itself could be verified to produce correct output for all the cases we&#39;ve encountered where it falls over, we wouldn&#39;t have to do this manual verification step; we could just trust that it was right, because it has tests that indicate it&#39;s correct.  Of course it&#39;s possible there might be *some* corner-case it still doesn&#39;t handle and that we didn&#39;t find, but if the tool is known to be broken in a large number of cases that we just have to magically know to avoid, then it&#39;s likely people will keep unknowingly re-introducing those problems.</div>
</div></div></blockquote><div><br></div><div style>More on this below.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><div></div><div>Second, there are going to be some doc patches in-progress whenever the cutover happens.  Now, this is a bit less of a concern, because we can just manually translate one or two paragraphs to the new markup if necessary.  But it would still be nice to have a tool that does the job well enough that someone could grab the buildbot output for an in-progress doc fix and keep working on it without having to learn how to re-express everything in Sphinx first.</div>
</div></div></blockquote><div> </div><div style>This is why I think (at this point) we need to build Sphinx docs for every branch as part of the buildbot process.  More below.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><div></div><div>Third, the output is just hella grody right now.  Have a look here, for example: &lt;<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html/989-37334/_sources/projects/web/howto/twisted-templates.txt" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html/989-37334/_sources/projects/web/howto/twisted-templates.txt</a>&gt;.  *Tons* of peculiarly and unnecessary vertical whitespace, and very ragged right edges where the word wrap doesn&#39;t seem to respect line lengths.  This means that every change that hits these documents is going to produce a lot of unnecessary delta when authors try to clean up some of this mess to make it nicer to edit.</div>
</div></div></blockquote><div> </div><div style>Yep, its&#39; ugly.  Lore2sphinx-ng does a better job, but isn&#39;t finished.  More below.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><div></div><div>Spot-checking some of the output now, it seems like the tool must have been upgraded, or we&#39;ve been lucky, since I can&#39;t spot any obvious bit-rot (and I could swear the docs look a lot less grody; the problems I mentioned there).  So maybe you&#39;ve already addressed these problems, or they&#39;re not actually that serious any more.  But, as I said in the first point, spot-checking isn&#39;t enough.</div>
<br><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>
It has been a pretty discouraging effort at times, I have to say, as I seem to garner agreement/support/buy-in/whatever for a particular course of action (e.g. getting 99% of the way there, and then fixing Sphinx markup manually, which was the original plan, way back when), and focusing my efforts in that direction.  Then when we&#39;re ready to proceed on that basis, had another task/challenge/set of requirements/whatever added to the work that needs to be done.  In fact I still think that if the Twisted community had actually wanted to, we could have switched over to Sphinx at the first PyCon Atlanta (2010?).</div>
</div></div></div></div></blockquote><div><br></div><div>By &#39;actually wanted to&#39; you mean &#39;be willing to abandon the development process for this one thing&#39;.</div><div><br></div><div>We do not abandon the development process.  Every past attempt at doing so to facilitate some feature has been a road to ruin.  Although this process has been frustrating for you, I am still happier with the current outcome (Twisted has perfectly functional documentation in our downloads and on our website) than with the alternative (create a situation where we could not produce a release for two years because the tools were languishing unfinished while we waited for you to say something about it).</div>
<div><br></div></div></div></blockquote><div><br></div><div style>You keep saying that I wanted to &quot;abandon the development process&quot;, and I&#39;m not sure what you mean by that.  My perception has been that I would say &quot;what do we need to do to make this happen&quot;?  There would be some hemming and hawing (and at least several times long discussions about how documentation didn&#39;t really fit the regular UQDS process) and a sort of plan would be invented.  I would proceed according to the plan as I understood it.  I would then say &quot;OK, we&#39;re ready&quot;!  And then be told that some other thing not in the plan needed to be done.  The cycle would then repeat.</div>
<div style><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word">
<div><div></div><div>I&#39;m sorry that this has been a frustrating process for you.  And I&#39;m not just saying that to be polite: I genuinely *am* sorry that our communication has not been clear, and that we have had wasted effort all around because of that.  But I am fairly sure that we have had basically the same requirements for this process from day one.  Let me state them here:</div>
<div><br></div><div><ol><li>We need to have release-automation tools that allow developers to produce a release, including documentation.  These tools need to be subjected to the same development process as the rest of those tools, which is to say the same process as for the rest of Twisted.</li>
</ol></div></div></div></blockquote><div style>No this was not brought up until well into the process. I (sort of) understand the desire for this, but it seems pretty weird to be building what is essentially a wrapper for an existing tool, along with tests for said wrapper, </div>
<div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div>
<ol><li>The documentation itself needs to be able to be generated from any version of trunk.  While one or two formatting snafus are acceptable to be fixed after the fact, the documentation needs to be in a comprehensible state in every revision of trunk, which means that in order to land on trunk, the ReST output.</li>
</ol></div></div></div></blockquote><div style>So...you didn&#39;t finish that sentence.  I realize you apologized for errors at the end of your mail, but I have a feeling you were going to say something rather important there...</div>
<div style><br></div><div style>:)</div><div style><br></div><div style>I&#39;ll talk more about this below (I think...depending on what you actually mean tot say here).</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><div><div></div><div>Really, most of the work has been done here already.  The docs appear to be in a mostly-workable state.  lore2sphinx looks like maybe it&#39;s doing a good enough job, maybe better than the last time I looked at it.  The _major_ hang-up is getting the release management tools over their final hump and just driving the trac tickets to completion.  With Tom keeping the review queue basically empty right now, this is an excellent opportunity to get that done.</div>
<div><br></div><div>It may make sense to schedule an event where we all show up on IRC, everyone claims a documentation component, and we all do a final review pass to make sure that the formatting problems aren&#39;t too bad before going to trunk with the cut-over.  This pre-supposes that the release/building tools are done and on trunk though.</div>
</div><br><blockquote type="cite"><div style="letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div>Anyway, I&#39;m not giving up.  If nothing else, I&#39;ll end up with a nice restructuredText-generating library.  And if Twisted never ends up adopting Sphinx as a doc tool, eventually I&#39;ll still be able to read the Twisted docs in a format that I can navigate and doesn&#39;t hurt my eyes to look at. :)</div>
<div><br></div><div>But I&#39;d really rather see Twisted adopt Sphinx, and get rid of Lore.</div><div><br></div><div>Help accepted.</div></div></div></div></div></blockquote><div><br></div><div>All right!  I hope this exchange has gotten some people fired up to cross the finish line.  It&#39;s surprisingly close!  Thanks for updating us, Kevin - better late than never :).</div>
<span class=""><font color="#888888"><div><br></div></font></span></div></div></blockquote><div><br></div><div style>Experience shows that it&#39;s unlikely to be surprisingly close.  I like your optimism though.</div><div>
 </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><span class=""><font color="#888888"><div>
</div><div>-glyph</div></font></span><div><br></div><div>P.S.: apologies for any errors.  I didn&#39;t even really have the time to write this email, let alone copy-edit it.</div><div><br></div></div></div></blockquote></div>
<div class="gmail_extra"><br></div><div class="gmail_extra" style>Now that I&#39;ve replied to all of that, let me give you a rundown of what I&#39;ve been thinking and planning, so that you have an idea of where I&#39;m coming from.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>Here are the various things that I have perceived to be necessary/required in order to get the conversion to happen:</div><div class="gmail_extra" style>
<br></div><div class="gmail_extra" style>a) The conversion process needs to be able to be run concurrently with Lore for an extended period of time.  In other words, Lore would be the &quot;official&quot; version of the docs, and the Sphinx docs would be built in some form of automated fashion until everyone was happy with them and/or ready to deprecate/abandon Lore.</div>
<div class="gmail_extra" style>b) Because of a), there needs to be tooling to run lore2sphinx (or whatever) on a regular basis.  (This was sort of being done via the Sphinx-building buildbot, but in a very ad-hockery sort of way, which was brittle, broke a couple of times, and needed to be improved.)</div>
<div class="gmail_extra" style>c) There needs to be release management tooling to build the Sphinx docs from ReST into whatever formats we want to publish (HTML and PDF to start, maybe others later on)</div><div class="gmail_extra" style>
d) Convert the Lore sources to better ReST documents without all the problems that the current lore2sphinx output has.  I at one time thought this was pretty impractical.  My first attempt at a conversion tool tried to use an intermediate object model, but I ran into trouble when trying to combine the various objects.  So I abandoned the effort and created what became lore2sphinx, which basically just combined a bunch of strings.  I then figured out a way of making the intermediate object thing work, and that was lore2sphinx-ng.  Then it became convenient to split out the intermediate object model from the documetn processing code, so I put all of that into a library and that became rstgen.<br>
</div><div class="gmail_extra" style><br></div><div class="gmail_extra" style>(For anyone who is curious, the lore2sphinx-ng repo is forked off from the lore2sphinx repo, primarily because I didn&#39;t want to break the Sphinx buildbot by making drastic changes.)</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>Here&#39;s what my plan was prior to this whole discussion getting started again.</div><div class="gmail_extra" style><br></div><div class="gmail_extra" style>
1) Finish rstgen, where &quot;finished&quot; in this instance is defined as &quot;is capable of generating all the vanilla docutils and sphinx-specific ReST elements that we need for converting the </div>Twisted documentation.</div>
<div class="gmail_extra">2) Finish lore2sphinx-ng (which would probably have ended with merging it back into the lore2sphinx repo), where &quot;finished&quot; means that it would be capable of processing all the XHTML Lore tags that were defined in the Lore documentation and used in the Twisted documentation, and generating a tree of rstgen elements, which could then be rendered into ReST.</div>
<div class="gmail_extra" style>(this would also serve to satisfy b) above, as the CLI in lore2sphinx-ng is less...well, let&#39;s just call it broken than lore2sphinx&#39;s was/is.)</div><div class="gmail_extra" style>3) Go back and finish SphinxBuilder (release tooling for building a sphinx project, which is basically a wrapper for sphinx-build, plus some vague &quot;version feature&quot;).</div>
<div class="gmail_extra" style>4) Get someone to use something less hackish than what&#39;s currently building the Sphinx docs on the buildbot, and preferably in such a way that the results of those builds could be published somewhere and have persistent links.  Currently the results of what the Sphinx buildbot does are stored for a time, and then go away, so you&#39;ll see links to build results in some trac tickets that go nowhere, which is decidedly unhelpful.  My plan was that we&#39;d set up something where the Sphinx docs would get generated and published someplace for every buildbot build so that we could always have the current results for the lore to sphinx conversion for the tip of each branch.  I have no idea whether this is actually feasible or practical, but it seemed like it would be useful.</div>
<div class="gmail_extra" style>5) Proceed with Sphinx docs being built from lore sources, making tweaks as necessary to lore2sphinx(ng) for as long as it took for the generated docs to be good enough to justify switching to Sphinx entirely.</div>
<div class="gmail_extra" style>6) Switch to Sphinx entirely.</div><div class="gmail_extra" style><br></div><div class="gmail_extra" style>I really wasn&#39;t planning on trying to get people excited about switching to Sphinx again until 1) and 2) were at least &quot;mostly&quot; done (for certain values of done) and I had gone back to finish 3).</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>So.  I guess at this point the question is whether to try and go with what&#39;s there (lore2sphinx) or finish up the &quot;new stuff&quot; (lore2sphinx-ng + rstgen).  I think 3-6 in my above plan need to happen in any case, and I think those will be much easier with lore2sphinx-ng+rstgen.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>I think I have some changes to lore2sphinx and rstgen which I haven&#39;t pushed yet.  I&#39;ll try to get those out there soonish (sometime over the weekend) in case people want to look at them.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>IIRC, rstgen has support for most of the vanilla docutils elements, with the notable exception of tables (and maybe definition lists...can&#39;t recall whether I finished those).  It has a basic level of test coverage (of course you can never have too many tests) for rendering the elements individually, and some test for elements in combination (particularly nested lists).  Footnotes and Citations I think also need some work, which I have a plan for, but haven&#39;t implemented yet (i don&#39;t think).</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>The &quot;new&quot; lore2sphinx CLI tool needs more work, but is relatively straightforward.  Like the old tool, it&#39;s basically an elementtree processor, except instead of spitting out strings that get joined together (which granted was an unholy mess), it generates rstgen elements, which all have a .render() method.  After processing a Lore document, you shoudl end up with a rstgen.Document object.  You call it&#39;s render() method, which calls it&#39;s children&#39;s render() methods, etc. and it&#39;s turtles all the way down.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>The framework is there for the new CLI tool, it&#39;s mostly a matter of writing a bunch of short methods that take elementtree elements as input and return appropriate rstgen objects.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>Obviously these tools aren&#39;t finished, but they produce much better output than the old version of lore2sphinx w.r.t. whitespace handling, paragraph wrapping, etc.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>Some of the code is still pretty messy, but nowhere near the train wreck that the current/old version of lore2sphinx is.  By which I mean it _can_ be cleaned up, it just hasn&#39;t been yet.  In particular there&#39;s some places in rstgen where the API is (to me at least) obviously awful, but I haven&#39;t gotten around to fixing it yet.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>Please review the code.  Please feel free to ask questions if you&#39;re interested.</div><div class="gmail_extra" style><br></div><div class="gmail_extra" style>
Personally, I&#39;ve gotten over being in a hurry about all this, and I think a robust tool is more likely to succeed in the long run, though finishing it may make the run a bit longer.  So I&#39;m for finishing lore2sphinx-ng+rstgen.</div>
<div class="gmail_extra" style><br></div><div class="gmail_extra" style>What are others&#39; opinions?  Make the &quot;old&quot; tool work?  Or make the &quot;new&quot; tool work?</div><div class="gmail_extra" style><br></div>
<div class="gmail_extra" style>Damn.  Talk about long emails.</div><div class="gmail_extra" style><br></div><div class="gmail_extra">--<br><div>Kevin Horn</div>
</div></div>