[Twisted-Python] Lore2sphinx current status

[Kevin Horn]

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.

====

The "current" version of lore2sphinx is here:
https://bitbucket.org/khorn/lore2sphinx

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.

Some time ago I forked that repo into this one:
https://bitbucket.org/khorn/lore2sphinx-ng

The plan for the NG branch is to:
a) split out the rendering of reStructuredText into a separate library.
 That library has it's own repo here: https://bitbucket.org/khorn/rstgen
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.
(the old/current version just created a bunch of strings and munged them
together, which has caused all kinds of ugliness)

b) rewrite/adapt lore2sphinx to use rstgen to generate reST

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.

Any future development should be handled on the lore2sphinx-ng "branch"
and/or the rstgen repo (both mentioned above).


Stuff that needs to be done:

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.

2) Rstgen could use some "convenience" elements, for example, elements for
specific directives, rather than just using the generic directive element
all the time.

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.

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.

5) clean up cruft and abandoned code in the lore2sphinx-ng repo.  There's a
lot of it.

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.


--
Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20130425/7e5ffea1/attachment.html>