<div dir="ltr">On Tue, Mar 26, 2013 at 3:41 PM, Glyph <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com" target="_blank">glyph@twistedmatrix.com</a>></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"><div class="im">On Mar 26, 2013, at 7:03 AM, Kevin Horn <<a href="mailto:kevin.horn@gmail.com" target="_blank">kevin.horn@gmail.com</a>> wrote:<br>
<div><br><blockquote type="cite"><div style="font-family:Menlo-Regular;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px">
- figure out a way to get Sphinx to take doctrees as input (I'm guessing you'd serialize them in whatever way Sphinx does when it does it's caching, stick them in the cache, and then get Sphinx to build from the cache?)</div>
</blockquote><br></div></div><div>This is the only part of the process I believe is actually necessary. All the other stuff you wrote assumes that this can't be made to work :). But as I understand it, this is specifically what JP asked Doug.</div>
</div></blockquote><div><br></div><div style>I don't think this (only needing to figure out the last part) is really the case:</div><div style><br></div><div style><div style="font-family:arial,sans-serif;font-size:13px">
- figure out the node output of every directive you were trying to replicate, with every type of (tedious in the best case, possibly very tricky for some directives, but maybe not too bad)</div><div style="font-family:arial,sans-serif;font-size:13px">
<br></div><div style="font-family:arial,sans-serif;font-size:13px">You need this to know what nodes to create in your tree. This doesn't seem too bad, until you realize that a number of the Sphinx-specific directives you *absolutely must have* (or at least the nodes they create, depend on the Sphinx build environment. So you need to either re-create the build environment, or you need to re-create all of these directives in your own code.</div>
<div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">- figure out a system to "inject" those nodes at the right time (not sure how difficult this would be)</div>
<div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">This one is probably not too bad, since you could probably get away with a bare minimum of just sticking your (for example) toctree nodes right after your main heading or something. And you could probably get away with something similar for index entries or whatever.</div>
<div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">- figure out how Sphinx modifies the doctrees to do all it's linking, index generation, toctree handling, etc. </div>
<div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">Probably not too much needs to be done here directly, as I *think* that Sphinx does all this after it builds the doctrees, so if you can get the doctrees into Sphinx you're probably fine. Don't quote me on that, though. So I no longer think this is the hardest part. But I think you'd still have to have a decent understanding of how these bits work internally to generate your nodes correctly. So a learning curve, though probably no actual code to write specifically for this.</div>
<div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">- figure out a way to get Sphinx to take doctrees as input (I'm guessing you'd serialize them in whatever way Sphinx does when it does it's caching, stick them in the cache, and then get Sphinx to build from the cache?)</div>
</div><div> </div><div style>Then you have to do this bit. The "obvious" way to do this is to create your doctrees and then pickle them, like Sphinx does when it caches parsed documents. Then make Sphinx build its output from these "cached" files (which I don't think it will currently do, but it can probably be made to do it).</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>The whole point is that we want to go straight from Lore->some docutils data structure. </div>
</div></blockquote><div><br></div><div style>Why? What does this buy us? To me it seems more complicated, requires more work, depends on *internal* APIs of a separate project (actually 2 separate projects), and doesn't seem to gain very much if anything. What's the reasoning here? Keep in mind that I'm without the benefit of whatever discussion on this took place at PyCon, so maybe I'm just missing something.</div>
<div><br></div><div style>If it's just an incremental transition, then I think we can get that without resorting to relying on the guts of two fairly complicated systems.</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>If we have to emit intermediary ReST, it's almost as bad as having to do the whole source translation in the first place.</div></div></blockquote><div><br></div><div style>I don't see how emitting intermediary ReST, which at least has a spec (granted the spec is ugly to look at, but it's pretty complete) is any worse than emitting intermediary doctrees, which could change out from under us.</div>
<div><br></div><div style>Summing up a bit:</div><div><br></div></div>Generating ReST is a challenging problem, no doubt. But it's the _only_ challenging problem if we go the source translation route.</div><div class="gmail_extra">
<br></div><div class="gmail_extra">If we go the doctrees route, I don't understand the advantage gained, and I'm concerned about dealing with the internals of docutils and Sphinx.</div><div class="gmail_extra"><br>
</div><div class="gmail_extra">(also it's more work, and I'm lazy :P )<br><br>--<div>Kevin Horn</div>
</div></div>