<div dir="ltr">Someone asked me off-list recently about how to help out with the Lore2Sphinx project. My response seemed like it would be generally helpful to anyone interested, and long enough that I wouldn't want to write it again, so I'm posting most of it here, for anyone else that is interested.<div>
<br></div><div>====<br></div><div><div><br></div><div><div>The "current" version of lore2sphinx is here: <a href="https://bitbucket.org/khorn/lore2sphinx">https://bitbucket.org/khorn/lore2sphinx</a></div><div><br>
</div><div>This is the version that is currently being used by the Twisted project in the documentation buildbot. However, it is brittle, and hard to modify, and in general doesn't do some things very well. It also hasn't been updated in some time. I consider it to be in stasis for the time being.</div>
<div><br></div><div>Some time ago I forked that repo into this one: <a href="https://bitbucket.org/khorn/lore2sphinx-ng">https://bitbucket.org/khorn/lore2sphinx-ng</a></div><div><br></div><div>The plan for the NG branch is to:</div>
<div>a) split out the rendering of reStructuredText into a separate library. That library has it's own repo here: <a href="https://bitbucket.org/khorn/rstgen">https://bitbucket.org/khorn/rstgen</a></div><div>Eventually I'd like for this library to be useful for any tool which wants to emit reStructuredText. The idea is that code using this library will create a tree of document elements, and each of which knows how to render itself into reST. Then you call the .render() element on the root element in that tree, and you get back some reST.</div>
<div>(the old/current version just created a bunch of strings and munged them together, which has caused all kinds of ugliness)</div><div><br></div><div>b) rewrite/adapt lore2sphinx to use rstgen to generate reST</div><div>
<br></div><div>c) clean up and extend command-line handling to make it easier to use lore2sphinx in different use-cases. For example, in the old/current version it was impossible to only convert a single file, or a single directory. You had to convert an entire Sphinx project all at once. This was pretty annoying and (I think) has been fixed now.</div>
<div><br></div><div>Any future development should be handled on the lore2sphinx-ng "branch" and/or the rstgen repo (both mentioned above).</div><div><br></div><div><br></div><div>Stuff that needs to be done:</div>
<div><br></div><div>1) Rstgen needs to support a few more core reST element types (by which I mean the ones supported in vanilla docutils). The one that comes to mind immediately is tables. There is some table support in the old/current version of lore2sphinx, which it might be possible to adapt. I haven't started on tables in the new version at all.</div>
<div><br></div><div>2) Rstgen could use some "convenience" elements, for example, elements for specific directives, rather than just using the generic directive element all the time.</div><div><br></div><div>3) I'd like Rstgen to also have specific support for generating Sphinx-specific elements, but I haven't started on this. Probably most of these will be subtypes of the document element types already present in rstgen. Examples include sphinx-specific directives, etc.</div>
<div><br></div><div>4) Rstgen needs to have some sort of Document object which represents an individual document, and has the ability to organize things like footnotes, citations, etc. There's a stub for this, but, like a platypus, it doesn't do much.</div>
<div><br></div><div>5) clean up cruft and abandoned code in the lore2sphinx-ng repo. There's a lot of it.</div><div><br></div><div>6) Finish re-writing the lore2sphinx code which generates rstgen elements. Some code for this is there already, but obviously there isn't anything for the elements that rstgen doesn't handle yet. Also, some of the code that is there isn't specific enough, and doesn't yet accurately represent the way that lore elements should be interpreted. The old lore2sphinx code which used strings does a pretty good job of this, I think, and is still in the repo, AFAICR (I did mention cruft, right?), so you might take a look at that for more details.</div>
<div><br></div><div> </div><div>--</div><div>Kevin Horn</div>
</div></div></div>